Thank you for considering to contribute to parallel-ssh. Any and all contributions are encouragaged and most welcome.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.

There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, contributing docker images for a particular task, submitting bug reports or feature requests or writing code to be incorporated into the project.

Please do not use the issue tracker for support questions. Use GitHub Discussions for that or other question/answer channels like Stack Overflow.

Please keep in mind the Code of Conduct when making contributions.

Responsibilities

• Write PEP-8 compliant code of no more than 100 columns per line - there is an automated test to check code for PEP-8.
• If adding new features, write an appropriate test - see existing tests for reference
• Contributions are expected to be in line with the project's stated design and goals
• Be welcoming to newcomers and encourage diverse new contributors from all backgrounds. See the Python Community Code of Conduct.

The best way to report an issue and to ensure a timely response is to use the issue tracker.

1. Create a GitHub account.

You need to create a GitHub account to be able to create new issues and participate in the discussion.

2. Determine if your bug is really a bug.

You shouldn't file a bug if you're requesting support. For that you can use GitHub Discussions.

3. Make sure your bug hasn't already been reported.

Search through the appropriate Issue tracker. If a bug like yours was found, check if you have new information that could be reported to help the developers fix the bug.

4. Check if you're using the latest version.

A bug could be fixed by some other improvements and fixes - it might not have an existing report in the bug tracker. Make sure you're using the latest release.

5. Collect information about the bug.

To have the best chance of having a bug fixed, we need to be able to easily reproduce the conditions that caused it. Most of the time this information will be from a Python traceback message, though some bugs might be in design, spelling or other errors on the documentation or code.

1. If the error is from a Python traceback, include it in the bug report.
2. We also need to know what platform you're running (Windows, Mac OS X, Linux, etc.), the version of your Python interpreter, the version of parallel-ssh, and related packages that were used when the bug occurred.

There is also an issue template to help with creating issues.

6. Submit the bug.

By default GitHub will email you to let you know when new comments have been made on your bug. In the event you've turned this feature off, you should check back on occasion to ensure you don't miss any questions a developer trying to fix the bug might ask.

Version numbers consists of a major version, minor version and a release number.

Versioning semantics described by SemVer are used.

All releases are published at PyPI when a versioned tag is pushed to the repository. All tags are version numbers, for example 1.0.0.

First you need to fork the parallel-ssh repository, a good introduction to this is in the GitHub Guide: Fork a Repo.

After you have cloned the repository you should checkout your copy to a directory on your machine:

$ git clone https://github.com/ParallelSSH/parallel-ssh.git

When the repository is cloned enter the directory to set up easy access to upstream changes:

$ cd parallel-ssh
$ git remote add upstream https://github.com/ParallelSSH/parallel-ssh.git
$ git fetch upstream

To update from upstream master branch use git pull:

git pull upstream master

If you need to work on a different branch than the one git calls master, you can fetch and checkout a remote branch like this:

git checkout --track -b 3.0-devel origin/3.0-devel

It is highly recommended that virtual environments are used for development and testing. This avoids system wide installation of dependencies, which may conflict with system provided libraries and other applications.

virtualenv dev_env
source dev_env/bin/activate

If you are developing, then you need to install development requirements first:

$ pip install -U -r requirements_dev.txt

$ pytest

When your feature/bugfix is complete you may want to submit a pull requests so that it can be reviewed by the maintainers.

Creating pull requests is easy, and also let you track the progress of your contribution. Read the Pull Requests section in the GitHub Guide to learn how this is done.

You can also attach pull requests to existing issues by referencing the issue number in the commit message, for example:

git commit -m "Fixed <some bug> - resolves #22"

will refer to the issue #22, adding a message to the issue referencing the commit and the PR, and automatically resolve the issue when the PR is merged.

See Closing issues using keywords for more details.

Pytest configuration always generates coverage reports.

pytest

coverage report -m will show the coverage report for any already run tests.

All supported Python versions are tested by the project's CI via test targets. Pull requests will trigger CI tests automatically. For running tests on your own forked repository follow CI documentation.

After these dependencies are installed you should be able to build the docs by running:

(cd docs; make clean; make html)

Make sure there are no errors or warnings in the build output. After building succeeds the documentation is available at _build/html.

Required packages are installed by requirements_dev.txt per instructions at Running the unit test suite.

To ensure all tests are passing before committing, run the following in the repository's root directory:

pytest

To ensure the code is PEP-8 compliant:

flake8 pssh

To ensure documentation builds correctly, if any changes have been made to documentation:

(cd doc; make html)

Generated documentation will be found in doc/_build/html in the repository's root directory.

All required checks are run automatically by the CI and on all pull requests.

You should probably be able to pick up the coding style from surrounding code, but it is a good idea to be aware of the following conventions.

• All Python code must follow the PEP-8 guidelines.

  flake8 and pep8 are utilities you can use to verify that your code is following the conventions.

  flake8 is automatically run by the project's Travis-CI based integration tests and is required for builds to pass.

  autoflake may be used in conjuction with IDEs to automatically adjust code to be compliant.

• Docstrings must follow the PEP-257 conventions.

• Docstrings for public API endpoints should include Sphinx docstring directives for inclusion in the auto-generated API documentation. For example:

  def method(self, arg):
      """Method for <..>
  
      :param arg: Argument for <..>
      :type arg: str
  
      :rtype: None
      """
  

  See existing documentation strings for reference.

• Docstrings for internal functions - ones starting with _ or __ - are not required.

• Lines should not exceed 80 columns.

• Import order

  • Python standard library (import xxx)
  • Python standard library (from xxx import)
  • Third-party packages.
  • Other modules from the current package.

  Within these sections the imports should be sorted by module name.

  Example:

  import threading
  import time
  
  from collections import deque
  from Queue import Queue, Empty
  
  from .platforms import Pidfile
  from .five import zip_longest, items, range
  from .utils.time import maybe_timedelta
  

• Wild-card imports must not be used (from xxx import *).

• Create a new release via Github releases for a new tag
• Select <create new tag on publish>
• Add release notes for tag via GitHub releases page

The version number is automatically calculated based on, in order of preference:

• Git tag
• Latest git tag plus git revision short hand since tag
• Auto-generated version file for non-git installations

Making a new release and creating a new tag for it will automatically create a new package version for that tag.

New git tags are automatically published to PyPi via CI deploy functionality, subject to all tests and checks passing.

This includes documentation generating correctly for publishing to ReadTheDocs, style checks via flake8 et al.

In addition to source code releases, binary wheel is also generated and published automatically and documentation is updated automatically on ReadTheDocs.

Publishing to PyPi and ReadTheDocs is only possible with CI build jobs initiated by the official GitHub project - forks cannot deploy to PyPi or publish documentation to ReadTheDocs.