diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 52888d0e2e..ec49a59d26 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,11 +1,11 @@ -Where to start +Where to Start -------------- -We eagerly welcome contributions of any type (e.g., bug fixes, new features, reporting issues, documentation, etc). If you're looking for a good place to get started you might like to peruse our current Git issues (those marked with `help wanted `_ are a good place to start). +We eagerly welcome contributions of any type (e.g., bug fixes, new features, reporting issues, documentation, etc). If you're looking for a good place to start, we recommend perusing our current Git issues (those marked with `help wanted `_ are a good place to start). -Please be aware of `Parsl's Code of Conduct `_. +Please be aware of `Parsl's Code of Conduct `_. -If you are not familiar with GitHub pull requests, the main mechanism to contribute changes to our code, there is `documentation available `_. +If you are unfamiliar with GitHub pull requests, the primary mechanism for contributing changes to our code, there is `documentation available `_. The best places to ask questions or discuss development activities are: @@ -14,25 +14,25 @@ The best places to ask questions or discuss development activities are: * using `GitHub issues `_. -Coding conventions +Coding Conventions ------------------ -Formatting conventions +Formatting Conventions ====================== Parsl code should adhere to Python `PEP-8 `_. This is enforced in CI (with some exceptions). You can also run this test yourself using ``make flake8``. -Naming conventions +Naming Conventions ================== -The following convention should be followed: ClassName, ExceptionName, GLOBAL_CONSTANT_NAME, and lowercase_with_underscores for everything else. +The following conventions should be followed: ClassName, ExceptionName, GLOBAL_CONSTANT_NAME, and lowercase_with_underscores for everything else. -Version increments +Version Increments ================== Parsl follows the `calendar versioning scheme `_ with ``YYYY.MM.DD`` numbering scheme for versions. -This scheme was chosen following a switch from ad-hoc versioning and manual release processes to an automated weekly process. -Releases are pushed from github actions to PyPI and will be picked up automatically by Conda. +This scheme was chosen after switching from ad-hoc versioning and manual release processes to an automated weekly process. +Releases are pushed from GitHub actions to PyPI and will be picked up automatically by Conda. Manual packaging instructions are included in the `packaging docs `_ @@ -50,14 +50,14 @@ Parsl uses ``pytest`` to run most tests. All tests should be placed in the ``parsl/tests`` directory. There are two broad groups of tests: those which must run with a -specific configuration, and those which should work with any +specific configuration, and those that should work with any configuration. -Tests which should run with with any configuration live under +Tests that should run with any configuration live under themed directories ``parsl/tests/test*/`` and should be named ``test*.py``. -They can be run with any configuration, by specifying ``--config CONFIGPATH`` +They can be run with any configuration by specifying ``--config CONFIGPATH`` where CONFIGPATH is a path to a ``.py`` file exporting a parsl configuration -object named ``config``. The parsl-specific test fixtures will ensure +object named ``config``. The Parsl-specific test fixtures will ensure a suitable DFK is loaded with that configuration for each test. Tests which require their own specially configured DFK, or no DFK at all, @@ -72,8 +72,8 @@ There is more fine-grained enabling and disabling of tests within the above categories: A pytest marker of ``cleannet`` (for clean network) can be used to select -or deselect tests which need a very clean network (for example, for tests -making FTP transfers). When the test environment (github actions) does not +or deselect tests that need a very clean network (for example, for tests +making FTP transfers). When the test environment (GitHub actions) does not provide a sufficiently clean network, run all tests with ``-k "not cleannet"`` to disable those tests. @@ -92,11 +92,11 @@ specified directly in the annotation - generally because they are broken in one way or another. -Coverage testing +Coverage Testing ================ There is also some coverage testing available. The CI by default records -coverage for most of the tests that it runs and outputs a brief report +coverage for most of the tests it runs and outputs a brief report at the end of each CI run. This is purely informational and a Lack of coverage won't produce a CI failure. @@ -119,10 +119,10 @@ Parsl development follows a common pull request-based workflow similar to `GitHu * all development occurs in branches (named with a short descriptive name, for example, `add-globus-transfer-#1`) * the master branch is always stable * development branches should include tests for added features -* development branches should be tested after being brought up-to-date with the master (in this way, what is being tested is what is actually going into the code; otherwise unexpected issues from merging may come up) -* branches what have been successfully tested are merged via pull requests (PRs) +* development branches should be tested after being brought up-to-date with the master (in this way, what is being tested is what is actually going into the code; otherwise, unexpected issues from merging may come up) +* branches that have been successfully tested are merged via pull requests (PRs) * PRs should be used for review and discussion -* PRs should be reviewed in a timely manner, to reduce effort keeping them synced with other changes happening on the master branch +* PRs should be reviewed in a timely manner to reduce effort in keeping them synced with other changes happening on the master branch Git commit messages should include a single summary sentence followed by a more explanatory paragraph. Note: all commit messages should reference the GitHub issue to which they relate. A nice discussion on the topic can be found `here `_. :: @@ -131,20 +131,20 @@ Git commit messages should include a single summary sentence followed by a more Added the ability to reference and automatically transfer Globus-accessible files. References are represented using the Parsl file format “globus://endpoint/path/file.” If Globus endpoints are known for source and - destination Parsl will use the Globus transfer service to move data to the + destination, Parsl will use the Globus transfer service to move data to the compute host. Fixes #-1. -Git hooks +Git Hooks --------- -Developers may find it useful to setup a pre-commit git hook to automatically lint and run tests. This is a script which is run before each commit. For example:: +Developers may find it useful to set up a pre-commit git hook to automatically lint and run tests. This is a script that is run before each commit. For example:: $ cat ~/parsl/.git/hooks/pre-commit #!/bin/sh make lint flake8 mypy local_thread_test -Project documentation +Project Documentation --------------------- All project documentation is written in reStructuredText. `Sphinx `_ is used to generate the HTML documentation from the rst documentation and structured docstrings in Parsl code. Project documentation is built automatically and added to the `Parsl documentation `_. @@ -152,4 +152,4 @@ All project documentation is written in reStructuredText. `Sphinx