-
Notifications
You must be signed in to change notification settings - Fork 27
Contributing
Thank you for your interest in contributing to AIT! We welcome contributions from people of all backgrounds and disciplines. While much of the focus of our project is software, we believe that many of the most critical contributions come in the form of documentation improvements, asset generation, user testing and feedback, and community involvement. So if you're interested and want to help out please don't hesitate! Send us an email on the public mailing list below, introduce yourself, and join the community.
All project communication happens via mailing lists. Discussions related to development should happen on the public Developer and User Mailing LIst. If you're new to the community make sure to introduce yourself as well!
If you're planning on contributing to the projects you'll want to make sure you have the packages installed in develop mode. You should also install the extra packages so you have the necessary additions for working with the documentation and tests.
> poetry install
> pip install -e ".[docs,tests]"
Install the Frontend dependencies with the below. You will need to have npm installed for frontend development.
> cd ait/gui/static
> npm install .
> pip install -e ".[docs,tests]"
All changes need to be made against one or more tickets for tracking purposes. AIT uses Github Issues along with Zenhub to track issue in the project. All tickets should have (outside of rare edge-cases):
- A concise title
- An in-depth description of the problem / request. If reporting a bug, the description should include information on how to reproduce the bug. Also include the version of the code where you’re seeing the bug.
If you’re going to begin work on a ticket make sure to progress the ticket through the various Pipeline steps as appropriate as well as assigning yourself as an Assignee. If you lack sufficient permissions to do so you can post on the ticket asking for the above to be done for you.
AIT projects take a fairly standard approach to commit message formatting. You can checkout Tim Pope's blog for a good starting point to figuring out how to format your commit messages. All commit messages should reference a ticket in their title / summary line.
Issue #248 - Show an example commit message title
This makes sure that tickets are updated on Github with references to commits that are related to them.
Commit should always be atomic. Keep solutions isolated whenever possible. Filler commits such as "clean up whitespace" or "fix typo" should be rebased out before making a pull request. Please ensure your commit history is clean and meaningful!
AIT makes a best-effort attempt at sticking with PEP-8 conventions. Please run your changes through a linter and stay compliant whenever possible!
We do our best to make sure that all of our changes are tested. If you're fixing a bug you should always have an accompanying unit test to ensure we don't regress!
Check the Developer Tips section below for information on running each repository's test suite.
All changes should be isolated to a feature branch that links to a ticket. The standard across AIT projects is to use issue-### for branch names where ### is the issue number found on Github.
The title of a pull request should include a reference to the ticket being fixed as mentioned for commit messages. The description of a pull request should provide an in-depth explanation of the changes present. Note, if you wrote good commit messages this step should be easy!
Any tickets that are resolved by the pull request should be referenced with Github's syntax for closing out tickets. Assuming the above ticket we would have the following in a pull request description:
Changes are required to be reviewed by at least one member of the AIT PMC/Committers groups, tests must pass, and the branch must be up to date with master before changes will be merged. If changes are made as part of code review please ensure your commit history is cleaned up.
Resolve #248
python setup.py nosetests or just nosetests to run the test suite
To run the frontend test suite
> cd ait/gui/static
> npm test
python setup.py nosetests or just nosetests to run the test suite
AIT uses Sphinx to build its documentation. You can build the documentation with:
> python setup.py build_sphinx
To view the documentation, open doc/build/html/index.html in a web browser.
If you need to update the auto-generated documentation you can run the following command to rebuild all of the ait package documentation:
> sphinx-apidoc --separate --force --no-toc -o doc/source ait ait/core/server/test ait/core/test
Please make sure to update the docs if changes in a ticket result in the documentation being out of date.