Contribute to stable-gym

Contribution guidelines

We love your input! 🚀 We want to make contributing to this project as easy and transparent as possible, whether it’s:

We Develop with Github

We use Github to host code, track issues and feature requests, and accept pull requests.

We Use Github Flow, So All Code Changes Happen Through Pull Requests

Pull requests are the best way to propose changes to the codebase (we use Github Flow). We actively welcome your pull requests:

  1. Fork the repo and create your branch from main.

  2. Add tests if you’ve added code that should be tested.

  3. If you’ve changed APIs, update the documentation.

  4. If you changed the documentation, please ensure it builds (see Documentation guidelines).

  5. Ensure the test suite passes (i.e. npm run test). If snapshots fail, please check if this is intended and update the snapshots if necessary using the npm run test:update:snapshots command.

  6. Make sure your code lints.

  7. Commit your changes.

  8. Create a pull request to pull the changes of your development branch onto the main branch.

  9. Ensure that all the pull request checks were successful.

[!NOTE]
When working on different machines, the snapshots could be slightly different. This is because the random seeds are sometimes dependent on the machine architecture. To fix this, please temporarily stash your changes or return to the latest upstream commit and run the npm run test:update:snapshots command. You can then add your change again and run the tests.

Report bugs using Github’s issues

We use GitHub issues to track public bugs. Report a bug by opening a new issue; it’s that easy!

Write bug reports with detail, background, and sample code

This is an example of a bug report, and I think it’s a good model. Here’s another example from Craig Hockenberry, an app developer greatly respected in the community.

Great Bug Reports tend to have:

  • A quick summary and/or background.

  • Steps to reproduce:

    • Be specific!

    • Give sample code if you can. A StackOverflow question includes sample code that anyone with a base R setup can run to reproduce the error.

  • What you expected would happen

  • What happens?

  • Notes (possibly including why you think this might be happening or stuff you tried that didn’t work).

People love thorough bug reports. I’m not even kidding.

Write descriptive commit messages

Ensure you add an excellent descriptive commit message to this repository. A good guide can be found here. When writing commit messages, please follow the conventional commits specifications. Additionally, you are recommended to check out the commitizen npm package, as it is beneficial in helping you write good commit messages.

Use a Consistent coding Style

We use several language guidelines to increase code quality, readability, and usability.

Python guidelines

Markdown guidelines

  • Linting and formatting: Please ensure your markdown code contains no errors and is formatted according to the remark-lint style guidelines.

GitHub actions

The Stable Gym package contains several GitHub actions, which check code changes against the language guidelines above. As a result, when the above guidelines are not met, you will receive an error/warning when you create a pull request. Some of these actions will make pull requests which you can use to fix some of these violations. For other errors/warnings, you are expected to handle them yourself before merging them into the main branch. If you think a coding guideline needs to be corrected or your code structure doesn’t allow you to respect the guideline, please state so in the pull request.

Pre-commit hooks

The Stable Gym package also contains several pre-commit hooks that enforce the guidelines above before committing. To enable these hooks, please:

  1. Install node.

  2. Install python.

  3. Run npm install . and pip install .[dev] to install husky and the required linters.

Release guidelines

Releases are handled automatically by the release-please-action. This action uses the release-please tool to create release pull requests based on the commits automatically. When writing commit messages, you must follow the Commit guidelines since this expects you to adhere to the conventional commits specifications. For more information on how this tool works, see the release-please documentation.

Documentation guidelines

See the documentation guidelines for more information on contributing to the documentation.

Any contributions you make will be under the MIT Software License

In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that’s a concern.