Ctrl+K

Contributing

Contributing#

First of all, thank you for contributing to the Software Gardening Almanack! 🎉 💯 🪴 We’re so grateful for the kindness of your effort applied to grow this project into the best that it can be.

This document contains guidelines on how to most effectively contribute to this project.

If you would like clarifications, please feel free to ask any questions or for help. We suggest asking for help from GitHub where you may need it (for example, in a GitHub issue or a pull request) by “at (@) mentioning” a Software Gardening Almanack maintainer (for example, @username).

Code of conduct#

Our Code of Conduct (CoC) policy (located here) governs this project. By participating in this project, we expect you to uphold this code. Please report unacceptable behavior by following the procedures listed under the CoC Enforcement section.

Security#

Please see our Security policy (located here) for more information on security practices and recommendations associated with this project.

Process#

Reporting bugs or suggesting enhancements#

We’re deeply committed to a smooth and intuitive user experience which helps people benefit from the content found within this project. This commitment requires a good relationship and open communication with our users.

We encourage you to file a GitHub issue to report bugs or propose enhancements to improve the Software Gardening Almanack.

First, figure out if your idea is already implemented by reading existing issues or pull requests! Check the issues (software-gardening/almanack#issues) and pull requests (software-gardening/almanack) to see if someone else has already documented or began implementation of your idea. If you do find your idea in an existing issue, please comment on the existing issue noting that you are also interested in the functionality. If you do not find your idea, please open a new issue and document why it would be helpful for your particular use case.

Please also provide the following specifics:

  • The version of the Software Gardening Almanack you’re referencing.

  • Specific error messages or how the issue exhibits itself.

  • Operating system (e.g. MacOS, Windows, etc.)

  • Device type (e.g. laptop, phone, etc.)

  • Any examples of similar capabilities

Your first code contribution#

Contributing code for the first time can be a daunting task. However, in our community, we strive to be as welcoming as possible to newcomers, while ensuring sustainable software development practices.

The first thing to figure out is specifically what you’re going to contribute! We describe all future work as individual GitHub issues. For first time contributors we have specifically labeled as good first issue.

If you want to contribute code that we haven’t already outlined, please start a discussion in a new issue before writing any code. A discussion will clarify the new code and reduce merge time. Plus, it’s possible your contribution belongs in a different code base, and we do not want to waste your time (or ours)!

Pull requests#

After you’ve decided to contribute code and have written it up, please file a pull request. We specifically follow a forked pull request model. Please create a fork of Software Gardening Almanack repository, clone the fork, and then create a new, feature-specific branch. Once you make the necessary changes on this branch, you should file a pull request to incorporate your changes into the main The Software Gardening Almanack repository.

The content and description of your pull request are directly related to the speed at which we are able to review, approve, and merge your contribution into The Software Gardening Almanack. To ensure an efficient review process please perform the following steps:

  1. Follow all instructions in the pull request template

  2. Triple check that your pull request is adding one specific feature. Small, bite-sized pull requests move so much faster than large pull requests.

  3. After submitting your pull request, ensure that your contribution passes all status checks (e.g. passes all tests)

We require pull request review and approval by at least one project maintainer in order to merge. We will do our best to review the code additions in as soon as we can. Ensuring that you follow all steps above will increase our speed and ability to review. We will check for accuracy, style, code coverage, and scope.

Git commit messages#

For all commit messages, please use a short phrase that describes the specific change. For example, “Add feature to check normalization method string” is much preferred to “change code”. When appropriate, reference issues (via # plus number) .

Development#

Overview#

We write and develop the Software Gardening Almanack in Python through Jupyter Book with related environments managed by Python Poetry. We use Node and NPM dependencies to assist development activities (such as performing linting checks or other capabilities). We use GitHub actions for CI/CD procedures such as automated tests.

Getting started#

To enable local development, perform the following steps.

  1. Install Python (suggested: use pyenv for managing Python versions)

  2. Install Poetry

  3. Install Poetry environment: poetry install

  4. Install Node (suggested: use nvm for managing Node versions)

  5. Install Node environment: npm install

  6. Install Vale dependencies: poetry run vale sync

  7. Optional: install book PDF rendering dependencies: poetry run playwright install --with-deps chromium

Development Tasks#

We use Poe the Poet to define common development tasks, which simplifies repeated commands. We include Poe the Poet as a Python Poetry dev group dependency, which users access through the Poetry environment. Please see the pyproject.toml file’s [tool.poe.tasks] table for a list of available tasks.

For example:

# example of how Poe the Poet commands may be used.
poetry run poe <task_name>

# example of a task which runs jupyter-book build for the project
poetry run poe build-book

Linting#

pre-commit automatically checks all work added to this repository. We implement these checks using GitHub Actions. Pre-commit can work alongside your local git with git-hooks After installing pre-commit within your development environment, the following command performs the same checks:

% pre-commit run --all-files

We strive to provide comments about each pre-commit check within the .pre-commit-config.yaml file. Comments are provided within the file to make sure we single-source documentation where possible, avoiding possible drift between the documentation and the code which runs the checks.

Automated CI/CD with GitHub Actions#

We use GitHub Actions to help perform automated CI/CD as part of this project. GitHub Actions involves defining workflows through YAML files. These workflows include one or more jobs which are collections of individual processes (or steps) which run as part of a job. We define GitHub Actions work under the .github directory. We suggest the use of act to help test GitHub Actions work during development.

Releases#

We utilize semantic versioning (“semver”) to distinguish between major, minor, and patch releases. We publish source code by using GitHub Releases available here. Contents of the book are distributed as both a website and PDF. We distribute a Python package through the Python Packaging Index (PyPI) available here which both includes and provides tooling for applying the book’s content.

Publishing Software Gardening Almanack releases involves several manual and automated steps. See below for an overview of how this works.

Version specifications#

We follow semantic version (semver) specifications with this project through the following technologies.

  • poetry-dynamic-versioning leveraging dunamai creates version data based on git tags and commits.

  • GitHub Releases automatically create git tags and source code collections available from the GitHub repository.

  • release-drafter infers and describes changes since last release within automatically drafted GitHub Releases after pull requests are merged (draft releases are published as decided by maintainers).

Release process#

  1. Open a pull request and use a repository label for release-<semver release type> to label the pull request for visibility with release-drafter (for example, see almanack#43 as a reference of a semver patch update).

  2. On merging the pull request for the release, a GitHub Actions workflow defined in draft-release.yml leveraging release-drafter will draft a release for maintainers.

  3. The draft GitHub release will include a version tag based on the GitHub PR label applied and release-drafter.

  4. Make modifications as necessary to the draft GitHub release, then publish the release (the draft release does not normally need additional modifications).

  5. On publishing the release, another GitHub Actions workflow defined in publish-pypi.yml will automatically build and deploy the Python package to PyPI (utilizing the earlier modified pyproject.toml semantic version reference for labeling the release).

  6. Each GitHub release will trigger a Zenodo GitHub integration which creates a new Zenodo record and unique DOI.

Citations#

We create a unique DOI per release through the Zenodo GitHub integration. As part of this we also use a special DOI provided from Zenodo to reference the latest record on each new release. Zenodo outlines how this works within their versioning documentation.

The DOI and other citation metadata are stored within a CITATION.cff file. Our CITATION.cff is the primary source of citation information in correspondence with this project. The CITATION.cff file is used within a sidebar integration through the GitHub web interface to enable people to directly cite this project.

Attribution#

We sourced portions of this contribution guide from pyctyominer. Big thanks go to the developers and contributors of that repository.

Contents