-
-
Notifications
You must be signed in to change notification settings - Fork 11
Development Guidelines
Work in progress can be tracked in ModularHistory's Jira workspace or on ModularHistory's public kanban board.
For instructions on setting up a development environment, see Dev Environment Setup.
All development efforts should be associated with an issue in Jira or in GitHub Issues.
Internal contributors should use Jira.
A Jira "issue" can be a Bug, a Story, or a Task. Issues can be viewed/created in ModularHistory's Jira workspace.
External contributors should use GitHub Issues.
Issues can be viewed/created at https://github.com/ModularHistory/modularhistory/issues.
To create branches without forking the project, you must be a repository member. (Otherwise, you can fork the project and then create a branch.)
Your branch name should be the issue number. For example, to create a branch for MH-100, you could use the following:
git checkout main && git pull
git checkout -b MH-100
Or, to create a branch for GitHub issue #234, you could use the following:
git checkout main && git pull
git checkout -b 234
- Keep your change set as succinct as possible (so that it is easy to review, test, debug, etc.).
- If you notice something that should be fixed or improved but is unrelated to your story/issue, create a separate issue and add a
TODO: <link to issue>comment above the problematic code.
- If you notice something that should be fixed or improved but is unrelated to your story/issue, create a separate issue and add a
- Commit your changes periodically!
- Before running database migrations, create a db backup:
python manage.py dbbackup
After adding some code, run tests:
poetry run invoke test
ModularHistory's Python tests are run with pytest and Coverage.py. Coverage.py provides information about what tests are missing (and need to be added).
To view an HTML report of the coverage results, run the following:
poetry run coverage html
Lint the code:
poetry run invoke lint
Fix any problems identified by the linters, then run tests again.
Push your changes:
git push
The output from this command should include a link to create a pull request. When you create the pull request,
If the change set is associated with a Jira issue, preface the title of the pull request with the issue key. For example, the title of the pull request could be MH-100: add JavaScript linter. This will automatically result in the pull request being linked to the Jira issue (so that Jira users can easily access the pull request).
If the change set is associated with a GitHub issue, add a comment to the pull request description saying closes <issue#>, e.g., closes 234. This comment will automatically cause the issue to be linked to your pull request, so that the issue is automatically closed after the pull request is approved and merged to the main branch.
To improve the odds of your pull request being reviewed quickly, you can tag one or more reviewers in a separate comment on the pull request (e.g., @jacob).