Skip to content

Latest commit

 

History

History
159 lines (109 loc) · 5.67 KB

CONTRIBUTING.rst

File metadata and controls

159 lines (109 loc) · 5.67 KB

Contributing

Issue Reports

If you experience bugs or in general issues with the package, please file an issue report on our issue tracker.

Code Contributions

Submit an issue

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

Create an environment

Before you start coding we recommend to install Miniconda which allows to setup a dedicated development environment named husky-ark with:

conda create -n husky-ark python=3

Note we like doing development in Python3 (and most tools only work in Python3, but the project must also run in Python2.7 to work on the Husky).

Then activate the environment husky-ark with:

conda activate husky-ark
conda install -c conda-forge pyscaffold tox

Clone the repository

  1. Create a Gitub account if you do not already have one.

  2. Fork the project repository: click on the Fork button near the top of the page. This creates a copy of the code under your account on the GitHub server.

  3. Clone this copy to your local disk:

    git clone git@github.com:YourLogin/husky_ark_armlab.git husky_ark_armlab
cd husky_ark_armlab

  4. You should run:

    pip install -U pip setuptools
pip install -e .[dev]

    Note if you are using zsh, you will need to replace .[dev] with .\[dev\].

  1. Install pre-commit:

    pre-commit install

    The husky_ark_armlab project comes with a lot of hooks configured to automatically help the developer to check the code being written.

  2. Create a branch to hold your changes:

    git checkout -b feature/(descriptive-feature-name)-(parent-branch)

    and start making changes. Never work on the master branch and you should almost always branch off develop. An example branch name could be feature/convert-yolo-to-xyxy-develop.

    You can also use release/ or hotfix/ as branch prefixes.

  3. Please follow the Conventional Commits commit message guidelines:

    Specifically, you should have both a commit title and body. Additionally, each commit title should start with one of the following prefixes:

    • FEAT: (new feature for the user, not a new feature for build script)
    • FIX: (bug fix for the user, not a fix to a build script)
    • DOCS: (changes to the documentation)
    • STYLE: (formatting, missing semi colons, etc; no production code change)
    • REFACTOR: (refactoring production code, eg. renaming a variable)
    • TEST: (adding missing tests, refactoring tests; no production code change)
    • CHORE: (updating grunt tasks etc; no production code change)

    Please see the existing commits for examples of what this should look like.

  4. Start your work on this branch. When you’re done editing, do:

    git add modified_files
git commit

    to record your changes in Git, then push them to GitHub with:

    git push -u origin feature/my-feature-develop

  5. Please check that your changes don't break any unit tests with:

    tox

    (after having installed tox with pip install tox or pipx). Don't forget to also add unit tests in case your contribution adds an additional feature and is not just a bugfix.

    To speed up running the tests, you can try to run them in parallel, using pytest-xdist. This plugin is already added to the test dependencies, so everything you need to do is adding -n auto or -n <NUMBER OF PROCESS> in the CLI. For example:

    tox -- -n 15

    Please have in mind that the husky_ark_armlab test suite is IO intensive (once someone gets around to writing it that is), so using a number of processes slightly bigger than the available number of CPUs is a good idea. For quicker feedback you can also try:

    tox -e fast

  6. Use flake8/black to checkfix your code style.

  7. Add yourself to the list of contributors in AUTHORS.rst.

  8. Go to the web page of your fork, and click "Create pull request" to send your changes to the maintainers for review. Find more detailed information creating a PR. You might also want to open the PR as a draft first and mark it as ready for review after the feedbacks from the continuous integration (CI) system or any required fixes.

Troubleshooting

I've got a strange syntax error when running the test suite. It looks like the tests are trying to run with Python 2.7 …

Try to create a dedicated venv using Python 3.6+ (or the most recent version supported by the package) and use a tox binary freshly installed in this venv. For example:

python3 -m venv .venv
source .venv/bin/activate
.venv/bin/pip install tox
.venv/bin/tox -e all