Contributing to Bocadillo
Hi, and thank you for your interest in contributing to Bocadillo! Here are a few pointers on how to contribute to this project.
Note: if the change you're proposing is non-trivial, you should open an issue first to discuss it with maintainers.
Bocadillo has a single repository for both the
bocadillo package and its documentation.
Note: you will need Python 3.6+ installed on your machine.
Setting up the repo
- Fork this repository and clone it on your machine.
- Install the dependencies:
python -m venv venv source venv/bin/activate pip install invoke invoke install
- If you plan to contribute documentation, make sure you have Node.js installed, and run:
Retrieving upstream changes
- Add this repo as an upstream:
git remote add upstream https://github.com/bocadilloproject/bocadillo.git.
- Check out the target branch, e.g.
git checkout master.
- Pull changes from the upstream remote repository:
git pull origin upstream.
Working with the repo
Common tasks are automated through Invoke:
- To run the
pytesttest suite, run:
- To generate a coverage report, run:
- To also only show lines not covered by tests, run:
invoke coverage --missing
- To serve the docs site (built with vuepress, hot reload enabled), run:
- To build the docs site, run:
npm run build
- The API reference is automatically generated with Pydoc-Markdown when serving or building the documentation. If you need to regenerate it manually, run:
- To add a new page to the docs, create a new
.mdfile in the appropriate subdirectory of
discussions), then add a route in the appropriate
docs/.vuepress/config.js. Feel free to refer to the VuePress docs if needed.
Formatting: this repo has a pre-commit hook that runs Black against your code before each commit.
Type annotations: we encourage you to provide type annotations (see typing) for functions, variables, methods and classes, e.g.:
def add(x: int, y: int) -> int: return x + y
Comments: code should be self-documenting. Only add comments to explain why a piece of code was implemented the way it was, and couldn't be simplified further.
Linting: this repo uses
pylintfor general-purpose linting and
mypyfor type checking. FYI, the Pylint configuration is located in
Pull Request process
- Make sure to open an issue before submitting a PR.
- Ensure your changes are well-commented, and you haven't left any commented-out lines or
- Make sure to update the documentation if necessary.
- Make sure you provided new tests for the feature or bug fix you are contributing.
- Your PR must pass the Travis CI builds. It will not be merged if the tests fail.
- Once the tests pass, your PR must be approved by a collaborator or maintainer before being merged in.
- Your PR has been merged, congrats!
Notes to maintainers
This section is solely aimed at maintainers and owners of the Bocadillo repository.
Versioning is managed through bumpversion.
To bump the package to a new version, use:
nox -s bumpversion -- "patch | minor | major"
This will update the version and the changelog, commit the changes and create a new tag.
.bumpversion.cfg for configuration, and bumpversion official docs for all the available options.
When ready to release a new version:
- Update the package version (see versioning).
- Push the tagged commit to the remote repository:
$ git push --tags
A PyPI deploy will run at the end of the triggered Travis build.
stable branch must be kept up to date with the latest release. When you need to release a bug fix as soon as possible, here's how to proceed: