Contributing

Welcome to AutoSteper contributor’s guide.

This document focuses on getting any potential contributor familiarized with the development processes, but other kinds of contributions are also appreciated.

If you are new to using git or have never collaborated in a project previously, please have a look at contribution-guide.org. Other resources are also listed in the excellent guide created by FreeCodeCamp [1].

Please notice, all users and contributors are expected to be open, considerate, reasonable, and respectful. When in doubt, Python Software Foundation’s Code of Conduct is a good reference in terms of behavior guidelines.

Issue Reports

If you experience bugs or general issues with AutoSteper, please have a look on the issue tracker. If you don’t see anything useful there, please feel free to fire an issue report.

Tip

Please don’t forget to include the closed issues in your search. Sometimes a solution was already reported, and the problem is considered solved.

New issue reports should include information about your programming environment (e.g., operating system, Python version) and steps to reproduce the problem. Please try also to simplify the reproduction steps to a very minimal example that still illustrates the problem you are facing. By removing other factors, you help us to identify the root cause of the issue.

Documentation Improvements

You can help improve AutoSteper docs by making them more readable and coherent, or by adding missing information and correcting mistakes.

AutoSteper documentation uses Sphinx as its main documentation compiler. This means that the docs are kept in the same repository as the project code, and that any documentation update is done in the same way was a code contribution.

When working on documentation changes in your local machine, you can compile them using tox:

tox -e docs

and use Python’s built-in web server for a preview in your web browser (http://localhost:8000):

python3 -m http.server --directory 'docs/_build/html'

Code Contributions

Submit an issue

Before you work on any non-trivial code contribution it’s best to first create a report in the issue tracker to start a discussion on the subject. This often provides additional considerations and avoids unnecessary work.

Setup environment

Prepare a conda environment:

conda create -n AutoSteper python=3.8
conda activate AutoSteper

Collect packages

To install from the source code, the AutoSteper package:

git clone https://github.com/Franklalalala/AutoSteper
cd AutoSteper
pip install . -e

The FullereneDataParser package:

git clone https://github.com/XJTU-ICP/FullereneDataParser
cd FullereneDataParser
pip install . -e

Warning

FullereneDataParser contains part of C++ code, to properly install, an advanced compiler version is required. Simply load the highest available version of compiler will avoid most of the problems.

To compile the usenauty project, please follow instructions in usenauty.

Submit your contribution

AutoSteper implements GitHub Actions to perform version control. To trigger an effective response, commit messages needs to stay in line with Conventional Commit messages.

Troubleshooting

Load the highest version of the aviable compiler in your enviroment will solve most of the problems. If not, lower the version requirement may help.

[1]

Even though, these resources focus on open source projects and communities, the general ideas behind collaborating with other developers to collectively create software are general and can be applied to all sorts of environments, including private companies and proprietary code bases.