Contributing¶

The Flux Framework team welcomes all contributors for bug fixes, code improvements, new features, simplifications, documentation, and more. Please do not hesitate to contact us with any questions or concerns.

This guide details how to contribute to Flux Framework projects in a standardized and efficient manner. Our projects follow the Collective Code Construction Contract (C4.1) which describes an optimal collaboration model for open source projects, based on the GitHub fork+pull model.

Pull Requests¶

Pull requests are the primary way code changes are incorporated into Flux Framework projects. All projects use the GitHub fork and pull model, in which contributors develop on a branch of their personal fork of the project and create pull requests in order to request those changes be merged into the main repository.

Use a pull request (PR) toward a repository’s master branch to propose your contribution, including the specific issue number your PR resolves. If you are planning significant code changes, or have any questions, please open an issue and reference it in your PR. To contribute to a Flux Framework project:

• Fork the project.

• Clone your fork. git clone git@github.com:[username]/flux-framework/[project].git

• Create a topic branch to contain your change. git checkout -b new_feature

• Create feature or add fix, and add tests if possible.

• Make sure everything still passes make check.

• Rebase your commits into meaningfully labeled, easily digestible chunks, ideally without errors.

• Push the branch to your GitHub repo. git push origin new_feature

• Create a PR against flux-framework/[project] and describe what your change does and why you think it should be merged. List any outstanding “to do” items.

• Each PR will be subjected to automated tests.

Please note that PRs should be rebased onto the master of the target repository, merge commits will be rejected by the pr-validator script.

PRs that are a work in progress are welcomed, but should have WIP: prefix or work-in-progress label to avoid automerging by mergify.io.

Developer Guidelines¶

• Review other issues and PRs to ensure you are not duplicating effort.

• When possible, submissions should include relevant unit and system tests. Coverage reports will be autogenerated for all submitted PRs.

• Update any appropriate documentation or open an issue to do so.

• Adhere to the coding style guide. The components of Flux written in C follow the Kernighan & Ritchie coding style, with exceptions enumerated in RFC 7. The components of Flux written in Python follow the black code style.

• Commit etiquette:

  • Avoid merge commits.

  • Separate work so that each commit fixes one problem. For example, keep code cleanup and refactoring in separate commits from new features, fixes, or functionality changes.

  • Use subsystem: prefix in commit titles. The subsystem name should be the minimal text needed to reference what has changed, without wasting too much of the commit subject character limit. For example, broker:, kvs: or doc: are good names, lib: or job: are not.

  • Reference related issues in the commit body.

  • Each commit should have a message with title and body as described in C4.1 (e.g., imperative phrasing, wrap lines at 72 characters).

For more details about C4.1, including commit requirements, see RFC 1.