Contribution

All kinds of contributions are welcome:

  • Improvement of code with new features, bug fixes, and bug reports

  • Improvement of documentation

  • Additional tests

If you want to contribute to code:

  1. Fork the latest main branch

  2. Install pyswarming

  3. Write failing tests

  4. Write new code

  5. Run tests and make sure they pass

  6. Update documentation

  7. Format code

  8. Pull Request

If you have any ideas or questions, feel free to open an issue.

1. Fork pyswarming

This consists of three main steps:

  1. Forking pyswarming

  2. Cloning your forked repo

  3. Sync your fork with the original pyswarming repo

A fork is simply a copy of a repository. It allows to freely experiment with changes without having an effect on the original project. The easiest way to fork a repository (first step) is by using the web interface on GitHub.org:

  1. Navigate to pyswarming repository.

  2. Click Fork in the top-right corner of the page.

  3. Follow the procedure (select owner, add a description, etc.)

  4. Click Create fork.

Then you need to clone your forked repo by using the command line:

$ git clone https://github.com/YOUR-USERNAME/pyswarming pyswarming

Finally, you need to sync your repository to the upstream (original project) pyswarming repository:

$ cd pyswarming
$ git remote add upstream https://github.com/mrsonandrade/pyswarming.git

Verify the new upstream repository by:

$ git remote -v

For more information about fork, you can visit the GitHub docs.

2. Install pyswarming

First, navigate to the directory, where your clone of tesspy is located. Install tesspy using:

$ python setup.py

This way, you have installed tesspy.

3. Write failing tests

It is a good practice to start writing tests even before writing any code. All the tests should initially fail. Think about your desired feature and write corresponding test cases. All tests are in the tests directory. New tests must also be saved here. For more info on Test-driven development, take a look here.

4. Write new code

Then it is time to start modifying the code, writing new functions, building new features, etc. You should write to the point when your initially created test cases pass.

5. Run tests

You should then run the test suit inside your own clone of the repository using pytest.

6. Update documentation

pyswarming documentation is in the folder docs. It is written using reStructuredText, which is explained here.

After adding any code or feature, please also add to the documentation. Make sure to check the documentation to build correctly by rendering it using sphinx.

7. Format code

pyswarming uses the PEP8 standard and black to ensure a consistent code format throughout the project.

So, before committing your changes, format the code using black.

it is a good idea to integrate black into your IDE. For example, it is explained here how to use black with pycharm.

8. Pull Request

When you’re finished making your changes and have made sure everything is working properly, you can submit a Pull Request. You can find more information on PRs here.