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#

Edgegraph utilizes the Ruff linter and formatter to ensure code quality. Ruff incorporates a number of features, replacing the previously-used Black formatter, Pylint linter, and numerous Flake8 extensions.

Both the formatter and linter are invoked during GitHub Actions runs, but neither will automatically commit any changes. Failing format or lint checks will cause the action to fail; the developer is expected to fix all format and lint failures before pushing code.

Note

The formatter is only run against the latest Python version in the pipeline. The linter is run on all advertised versions of Python.

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

  • ruff check to run linting checks

  • ruff format --check to only check, without applying any edits, which of the files (if any) Ruff will want formatted.

  • ruff format to apply formatting changes

See the Ruff documentation for more info.

Type checking#

Edgegraph is a fully type-hinted library, using MyPy as its type checker. MyPy is run automatically on all pull requests; but does not fail a build; there remain about a dozen known issues. However, pull requests that add more failures will not be accepted.

You can run type checking locally on your machine with the following invocation(s):

  • mypy edgegraph to check the entire library. This is what is run on the GitHub actions pipeline.

  • mypy edgegraph/traversal/helpers.py to check a single file

  • mypy edgegraph/traversal/helpers.py --follow-imports=silent to check a single file, but not reporting errors in modules it imports (recommended for rapid-fire fixups of a single module, it keeps the error report focused on the module you’re working on)

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:

    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.

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

  4. 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 and changelog are up to date.

  5. 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.

  6. 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.

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

  8. 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

  9. Back-merge the release into the develop branch.

    1. git checkout develop

    2. git merge master

  10. 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