Contributing to Bocadillo
What is this document about?
Have you found a bug? You'd like to add a new feature or improve the docs? Fantastic news! All contributions are happily welcome.
Here, we point at a few guidelines that you should follow in order to get your contribution accepted.
Always discuss ideas!
Before submitting any code changes for review, you should first open an issue so that maintainers and contributors can discuss it with you.
This step is important because there may be aspects you didn't think about, or there may be ways to expand or focus your suggestions. Eventually, discussing your suggestions with others can only improve the quality of the contribution you'll make.
Bocadillo has a single repository for both the
bocadillo package and its documentation.
Setting up the repo
Here's how to get your copy of the repo ready for development:
- Fork the
- Clone the repo on your computer:
git clone https://github.com/<your-username>/bocadillo.
- Checkout the
masterbranch and grab its latest version:
git pull origin master.
- Install the project (see installation steps below).
- Create a branch (e.g.
fix/some-bug) and work on it.
- Push to your remote:
git push origin fix/some-bug.
- Open a pull request and follow the PR process below.
Installing Bocadillo for development
In order to install Bocadillo for development, you'll need Python 3.6+.
Project dependencies are managed through Pipenv. You should install it if you haven't already:
pip install pipenv
Then run the following in order to install dependencies:
pipenv install --dev
To verify Python dependencies have been correctly installed, first run the tests. You can also fiddle with Bocadillo in the interpreter:
>>> import bocadillo >>> bocadillo.__version__ '0.11.2'
Installing pre-commit hooks
This repo has a pre-commit hooks that runs Black (see Black formatting) against your code before every commit.
After installing dependencies, you should install the hooks using the following command:
Installing the documentation packages
To verify the npm packages are correctly installed, you can fire up the docs site:
and access it at http://localhost:8080.
Before making any changes, you should first run the tests in order to make sure everything is correcly setup.
Bocadillo uses pytest as its testing framework. The test suite can be run using:
To also generate a coverage report, run:
There are a few extra things you need to known in order to contribute documentation for Bocadillo.
This section supposes that you have already installed Bocadillo's documentation dependencies.
Note: Bocadillo's documentation site is made with VuePress. You may need to refer to its documentation, although the main problems you'll encounter are listed here.
How the documentation is structured
All documentation lives in the
docs/ directory. It is structured as follows:
getting-started: resources for users getting started with Bocadillo.
guides: discussions about key topics and concepts, including background, information and usage hints.
how-to: recipes for solving key problems or addressing specific use cases.
discussions: these give more in-depth background about important topics or activities related to application development.
api: technical reference for Bocadillo's machinery, a majority of which is generated from the docstrings of Python modules, classes and functions.
faq: frequently asked questions.
Running the docs site
To run the documentation site, run:
It will be accessible at http://localhost:8080.
The docs site is hot-reloaded on any changes to the contents of the
The only exception to this is the generated API Reference. You'll need to generate it to visualise it locally — see Generating the API Reference.
Creating documentation pages
To write a new page for the docs, create a new
.md file in the appropriate directory (see How the documentation is structured), then add a route in the appropriate
sidebar configuration in
Feel free to refer to the VuePress docs if needed.
Generating the API Reference
Bocadillo uses Pydoc-Markdown to generate the API reference in Markdown format from Python docstrings. The generated
.md files are then wired up in the
In order to view the changes you've made to Python dosctrings in the docs site, or after your first install, you'll need to regenerate the API reference:
The docs site will reload and display the updated API Reference docs.
Debugging the docs site
It may happen that the documentation site does not seem to behave properly.
You should first open your browser's dev tools and check for any errors. VuePress errors generally give enough clues as to what's wrong and how you can fix it.
If there is an issue with VuePress' hot-reloading, you may need to close the current tab and open a fresh copy of the docs site in a new tab.
In practice, Black may intervene and reformat some of the Python files when committing to your local. When this happens, the commit will abort and you'll need to
git add files edited by Black and
git commit again.
If you wish to manually apply Black before a commit, run
Lastly, you can configure your IDE of choice to automatically format the code using Black (.e.g on save).
Bocadillo makes heavy use of type annotations in order to document input and output types of functions and methods, as well as facilitate early detection of bugs.
You are encouraged to provide annotations for each and every function and method you write.
def add(x: int, y: int) -> int: return x + y
def add(x, y): return x + y
For background on the benefits of type annotations, we recommend Stav Shamir's The other (great) benefit of Python type annotations.
If you need help when writing type annotations, be sure to check out the official documentation of the typing module.
Comments and docstrings are crucial in order to convey key information about the code. You should use them when needed.
Be sure, however, not to over-comment. Code should be self-documenting. For example, if you find yourself adding comments to delimit your code, it may be worth refactoring — e.g. into a few descriptively-named functions.
There are 3 types of code documentation you may find yourself using.
All modules should have a descriptive docstring at their top. For example:
"""Exception classes.""" class MyException(Exception): pass
Function, method or class docstrings
Every public function, method or class should have a proper docstring.
Here is an example of a compliant class with its methods:
"""Definition of the Foo class.""" import operator from functools import reduce class Foo: """Some really cool kind of foo. # Parameters bar (str): used to configure XYZ. """ def __init__(self, bar: str): self._bar = bar @property def zed(self) -> str: """z with an exclamation mark.""" return 'z!' def create_baz(self) -> int: """Create `baz` from the current `bar`. # Returns baz (int): multiplication the ASCII codes for each letter in `bar`. """ return reduce(operator.mul, map(ord, self._bar))
A comment is a line that starts with
#. There are two use cases to comments:
- To explain complex code that may not be easily understood by future developers.
- To explain why a portion of code was implemented the way it was.
As a rule of thumb, don't use comments to explain what your code is doing, but to explain why it's doing what it's doing. Again, code should be self-documenting. If you need to explain what your code is doing, try simplifying it into smaller components (functions, methods, objects) with descriptive names.
Linting refers to the process of running a program that will analyze the code base for potential errors. This repo uses two linters: Pylint and Mypy.
Pylint is used for general error checking. It has a lot of useful features which you can read about on the official website: pylint.org.
Pylint comes installed along with the development dependencies, and can be used to check for errors using:
FYI, the Pylint configuration is located in
Static type checking with MyPy
MyPy is installed along with the development dependencies, so you can manually type check the code base using:
We also encourage you to configure your IDE of choice to automatically type check the code using MyPy for you (e.g. on save).
Pull Request process
- Make sure to open an issue before submitting a PR (see Always discuss ideas). Note: not all features can be accepted, as some may be out-of-scope and would be better off as third-party packages. It would be sad if you worked on a PR for days but it gets rejected because of reasons that could have been quickly pointed at if you discussed it in an issue.
- Ensure your changes are well-commented and you haven't left any commented-out lines of code or debug
- If your changes imply additions or changes in interface, make sure to the documentation. This includes environment variables, file locations, extra keyword arguments, etc.
- You must add tests for the feature or bug fix you are providing.
- Your PR must pass the Travis CI builds. It will not be merged if the tests fail.
- The PR can be merged once it has obtained approval from at least one collaborator or maintainer.
Notes to maintainers
This section is solely aimed at maintainers and owners of the Bocadillo repository.
Versioning is managed through bumpversion.
The utility script
bumpversion with all the provided arguments*, bumps the changelog and creates a tagged commit for the new version.
bash scripts/bumpversion.sh "patch | minor | major"
Tip: you may want to
chmod +x scripts/bumpversion.shto use
*See bumpversion official docs for all the available options and
.bumpversion.cfg for the default configuration.
This section documents how to release new versions to PyPI.
It is recommended to make a test release to TestPyPI before releasing a new version to production.
You can do so by pushing to the
- Grab the latest version from
git checkout release/test git merge master
If the current version has already been released to TestPyPI, update the package version (see versioning).
Push to remote:
When ready to release a new version to production:
Update the package version if necessary (see versioning).
Push the tagged commit to remote:
$ git push --tags