Skip to content

Latest commit

 

History

History
126 lines (78 loc) · 4.27 KB

CONTRIBUTING.md

File metadata and controls

126 lines (78 loc) · 4.27 KB
Raw

Contributing to LTIAuthenticator

Welcome! As a Jupyter project, you can follow the Jupyter contributor guide.

Make sure to also follow Project Jupyter's Code of Conduct for a friendly and welcoming collaborative environment.

Setting up a development environment

LTIAuthenticator requires Python >= 3.8.

  1. Clone the repo:

    git clone https://github.com/jupyterhub/ltiauthenticator

  2. Install the development requirements, which include things like linting and testing tools:

    python3 -m pip install -e ".[dev,test]"

  3. Set up pre-commit hooks for automatic code formatting and linting:

    pre-commit install

    You can also invoke the pre-commit hook manually at any time with:

    pre-commit run

Contributing

The LTIAuthenticator has adopted automatic code formatting so you shouldn't need to worry too much about your code style. As long as your code is valid, the pre-commit hook should take care of how it should look. You can invoke the pre-commit hook by hand at any time with:

pre-commit run

which should run any autoformatting on your code and tell you about any errors it couldn't fix automatically. You may also install black integration into your text editor to format code automatically.

If you have already committed files before setting up the pre-commit hook with pre-commit install, you can fix everything up using pre-commit run --all-files. You need to make the fixing commit yourself after that.

Testing

It's a good idea to write tests to exercise any new features, or that trigger any bugs that you have fixed to catch regressions.

From the root of the repo, you can run the tests with:

pytest -v

If you want to just run certain tests, check out the pytest docs for how pytest can be called. For example:

pytest -v -k spawn ltiauthenticator/tests/test_lti.py

Commit Messages, Changelog, and Releases

This project includes pre-commit hooks configured to run black, flake8, and pip-compile before running and completing the git commit ... command. If these tools do not run when running the git add ... and git commit ... commands, make sure you install the pre-commit hooks with pre-commit install.

For Contributors

Once a new version is released, assets should be published with the new tag, such as docker images, pip/npm packages, and GitHub repo release tags.

For the most part, contributors do not need to worry about commit message formats, since all commits from a Pull Request are squashed and merged before merging to main. Commit messages are updated to the standard format during this step.

For Maintainers

Pull Requests and Commits

When squashing and merging to the main branch, use the following format to provide consistent updates to the CHANGELOG.md file:

<Commit Type>(scope): <Merge Description>

  • Merge Description should initiate with a capital letter, as it provides the changelog with a standard sentence structure.

  • Scope is used to define what is being updated. Our current scopes include:

  1. lti11
  2. lti13
  • Commit Types are listed below:
Commit Type Commit Format
Chores chore
Documentation docs
Features feat
Fixes fix
Refactoring refactor

Use the BREAKING CHANGE in the commit's footer if a release has a breaking change.

Examples:

  • Commit a new feature:

    feat(lti11): Add custom handler to fetch XML configuration

  • Commit a bug fix:

    fix(lti13): Fix authentication bug from Assignment links

  • Commit a version with a breaking change:

    feat(core): Deprecate observer role from group memberships

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Releases

Please refer to the documentation within this repo's RELEASE.md.