Development Practices

Development Practices#

As a project, Edgegraph intends to use the most up-to-date, complete Python development practices. This includes unit testing, documentation, and code formatting and quality standards. It is expected to perform flawlessly on all supported versions of Python at any given moment, and if only trivial changes are required to support EOL’d versions of Python, limited effort may be made to do so.

Formatting#

Black is employed to automatically format code in-place, alongside pylint for further code quality checks. Both are automatically invoked during GitHub Actions runs on pull requests and certain branches; but neither (Black especially) are configured to automatically commit any changes. Black will cause the actions run to fail if files are not formatted; the developer is expected to perform this formatting locally before pushing code. Pylint checks are provided for information only, and do not have a failure threshold – however, the maintainer of Edgegraph reserves the right to reject pull requests if they are sufficiently detrimental in the pylint scorecard :)

You can run these checks locally on your machine with the following invocations:

  • black --check edgegraph tests docs to only check, without applying any edits, which files (if any) Black will want formatted.

  • black edgegraph tests docs to apply Black formatting changes.

  • pylint edgegraph tests to check Pylint results

Version Control#

Git provides version control for the Edgegraph project, and GitHub is the primary collaboration point. Core maintainers (should there ever be more than one…) are expected to follow the Git Flow model on branching within the repository with a minor change to the widely accepted model. Instead of release branches merging directly into both master and develop, release branches are merged into master which is then in turn merged into develop. This approach ensures the version number-tagged commit is present in develop’s history as well as master.

Contributions from anyone are always welcome; please utilize the GitHub Flow (also sometimes known as the “fork-and-pull”) model, targeting pull requests to the develop branch.

Branch name pattern

Usage

master

Formally released, tagged, version numbered releases are here. This branch is merge commits only; and only from release or hotfix branches.

release/v\d.\d.\d

Release integration, final quality checks, readme and documentation finalizations happen here. Release branches are branched from develop and merge into master.

hotfix/.*

Hotfix branches focus, again, on eliminating bugs. However, it is permissible for hotfix branches to fix multiple bugs, should it be most sensible. Unlike bugfix branches, hotfix branches branch from and merge into master; therefore, they necessitate a patch-level version increment.

develop

Long-running feature integration and shakeout. This branch is also sometimes known as the “nightly” version, and stability is not guaranteed.

bugfix/.*

Bugfix branches are focused on eliminating a single bug. They branch from and merge into develop.

feature/.*

Each feature branch is focused on, well, a single feature. These branch from and merge into develop.

sandbox/.*

Sandbox branches may be used for testing of ideas, large-scale refactors or changes, what-if analyses, etc.. They are used identically to feature branches, but with less guarantee of stability or eventual closure.

Release Procedure#

Every versioned release of Edgegraph is expected to undergo the following steps. Some differences are naturally driven by the difference between the normal release route, and more urgent hotfixes. Much effort has been given to automating as much of this process as possible, and such efforts are expected to continue. However, some aspects of the release process should involve human intervention and authority; notably, merging of the releasing pull request and upload to PyPI.

  1. A version number is identified. This number shall increment in accordance with Edgegraph’s versioning standard.

  2. Create a new branch from develop, named release/vversion number. For example, release/v0.4.0 would be correct.

  3. Create a new branch:

    1. For normal releases (that is, major and minor releases), branch from develop. The branch name should be of the form release/vX.Y.Z.

    2. For urgent hotfixs (that is, patch releases), branch from master. The branch name should be of the form hotfix/issue.

  4. Update the release number in edgegraph/version.py as needed. This is the ONLY place where the version number is kept.

  5. Ensure all applicable documentation for new features, bugfixes, etc. is created, and all prior existing documentation is updated with any relevant changes. Ensure the README.md feature list is up to date.

  6. Commit these changes, and push. GitHub Actions will ensure that all unit tests pass, code coverage is at 100%, and documentation build is working. Ensure the actual documentation product is as you expect on ReadTheDocs.

  7. Open a GitHub pull request into the master branch.

    1. At this point, the normal peer review cycle takes place, with reviewers (hopefully) leaving comments. GitHub Actions will continue to perform its automated checks.

  8. Once all reviews are satisfied, merge the pull request.

  9. Tag the commit on the master branch with the applicable version number.

    1. On your machine, ensure you pull the latest master branch.

    2. git tag vX.Y.Z

    3. git push origin master

  10. Back-merge the release into the master branch.

    1. git checkout develop

    2. git merge master

  11. Upload the build to PyPI.

    1. Switch back to the master branch; more specifically the version tagged commit (git checkout vX.Y.Z).

    2. If the dist folder exists, delete it and any of its contents.

    3. Run scripts/pypi.sh

Contents