Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update broken CoC link and minor grammar changes #3749

Merged
merged 1 commit into from
Jan 16, 2025
Merged

Update broken CoC link and minor grammar changes #3749

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 27 additions & 27 deletions CONTRIBUTING.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <https://github.com/Parsl/parsl/labels/help%20wanted>`_ 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 <https://github.com/Parsl/parsl/labels/help%20wanted>`_ are a good place to start).

Please be aware of `Parsl's Code of Conduct <https://github.com/Parsl/parsl/blob/master/CODE_OF_CONDUCT.md>`_.
Please be aware of `Parsl's Code of Conduct <https://github.com/Parsl/.github/blob/main/CODE_OF_CONDUCT.md>`_.

If you are not familiar with GitHub pull requests, the main mechanism to contribute changes to our code, there is `documentation available <https://opensource.com/article/19/7/create-pull-request-github>`_.
If you are unfamiliar with GitHub pull requests, the primary mechanism for contributing changes to our code, there is `documentation available <https://opensource.com/article/19/7/create-pull-request-github>`_.

The best places to ask questions or discuss development activities are:

Expand All @@ -14,25 +14,25 @@ The best places to ask questions or discuss development activities are:
* using `GitHub issues <https://github.com/Parsl/parsl/issues>`_.


Coding conventions
Coding Conventions
------------------

Formatting conventions
Formatting Conventions
======================

Parsl code should adhere to Python `PEP-8 <https://peps.python.org/pep-0008/>`_. 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 <https://calver.org/#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 <http://parsl.readthedocs.io/en/latest/devguide/packaging.html>`_

Expand All @@ -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,
Expand 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.

Expand All @@ -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.

Expand All @@ -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 <https://chris.beams.io/posts/git-commit/>`_.
::
Expand All @@ -131,25 +131,25 @@ 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 <http://sphinx-doc.org/>`_ 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 <https://parsl.readthedocs.io>`_.

Credit and Contributions
------------------------

Parsl wants to make sure that all contributors get credit for their contributions. When you make your first contribution, it should include updating the codemeta.json file to include yourself as a contributor to the project.
Parsl wants to ensure that all contributors receive credit for their contributions. When you make your first contribution, you should update the codemeta.json file to include yourself as a contributor to the project.