Skip to content

Latest commit

 

History

History
148 lines (112 loc) · 6.67 KB

contributing.rst

File metadata and controls

148 lines (112 loc) · 6.67 KB

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.

Testing

Testing is an important part of development throughout all of the Flux components, and any changes or additions contributed should come with adequate testing.

Unit tests are generally co-located with sources and use libtap. System tests are generally located under the t/ directory and use sharness.

The below examples show how to run tests in a Flux project within their respective t/ directories.

To run a single test within the test harness, specify the test file on the command line:

$ ./t0000-testname.t -d -v

Python tests can also be run directly, but to get the correct PYTHONPATH for your build directory, run under flux(1):

$ ../src/cmd/flux ./python/t0000-test.py

or:

$ src/cmd/flux start
$ ./python/t000-testname.py

Other Helpful Testsuite Tips

  • Use the make check-prep target at the top-level build directory of flux-core to make everything necessary for running tests, but without running any of the tests under ./t. This is useful if you then want to run only a specific test, or run all tests as Flux jobs, e.g. flux mini bulksubmit --watch --progress ./{} ::: t[0-9]*.t python/t*.py lua/*.t
  • Running all tests in Flux takes some time. If you are developing a feature and only a few tests are failing, make recheck can be useful; it will only re-run failing tests. This makes for a more efficient develop-test-debug cycle.
  • Many sharness tests re-run themselves under a Flux instance using the test_under_flux function.
  • For these tests you can set FLUX_TEST_VALGRIND=t and all flux-brokers in the test instance will be run under valgrind for memory debugging. (This is also useful to tease out race conditions in your test code), e.g.:
$ FLUX_TEST_VALGRIND=t ./t0000-testname.t -d -v
sharness: loading extensions from /home/grondo/git/f.git/t/sharness.d/01-setup.sh
sharness: loading extensions from /home/grondo/git/f.git/t/sharness.d/flux-sharness.sh
==5906== Memcheck, a memory error detector
==5906== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
==5906== Using Valgrind-3.13.0 and LibVEX; rerun with -h for copyright info
==5906== Command: /home/grondo/git/f.git/src/broker/.libs/flux-broker --setattr=rundir=/tmp/flux-5803-

For more details about building and running tests, see our README.