Community¶
You can check out Kinto on Github at https://github.com/Kinto/kinto/.
Communication channels¶
- Questions tagged
kinto
on Stack Overflow. - Our IRC channel
#kinto
onirc.freenode.net
— Click here to access the web client - If you prefer to use slack, head over to: https://slack.kinto-storage.org/
- Our team blog http://www.servicedenuages.fr/
- The Kinto mailing list.
- Some #Kinto mentions on Twitter :)
How to contribute¶
Thanks for your interest in contributing to Kinto!
Note
We love community feedback and are glad to review contributions of any size - from typos in the documentation to critical bug fixes - so don’t be shy!
Report bugs¶
Report bugs at https://github.com/Kinto/kinto/issues/new
If you are reporting a bug, please include:
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Fix bugs¶
Check out the open bugs - anything tagged with the easy-pick label could be a good choice for newcomers.
Implement features¶
Look through the GitHub issues for features. Anything tagged with enhancement is open to whoever wants to implement it.
Write documentation¶
Kinto could always use more documentation, whether as part of the official docs, in docstrings, or even on the Web in blog posts, articles, and such.
This official documentation is maintained in Github, in the docs
directory. Just
run make docs
from the project root to convert the RST source
files into HTML output (in the docs/_build/html
directory). We
accept pull requests for this documentation, just as we accept them
for bug fixes and features!
Submit feedback¶
Any issue with the question label is open for feedback, so feel free to share your thoughts with us!
The best way to send feedback is to file a new issue on GitHub.
If you are proposing a feature:
- Explain how you envision it working. Try to be as detailed as you can.
- Try to keep the scope as narrow as possible. This will help make it easier to implement.
- Feel free to include any code you might already have, even if it’s just a rough idea. This is a volunteer-driven project, and contributions are welcome :)
Hack¶
Ready to contribute? Here’s how to set up Kinto for local development.
Get started!¶
Fork the Kinto repo on GitHub.
Clone your fork locally:
git clone git@github.com:your_name_here/kinto.git
Install and run Kinto locally (more details):
make serve
Create a branch for local development:
git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass the tests:
make tests
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Pull request guidelines¶
Note
Open a pull-request even if your contribution is not ready yet! It can be discussed and improved collaboratively!
Before we merge a pull request, we check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated.
- TravisCI integration tests should be green :) It will make sure the tests pass with every supported version of Python.
Hack core libraries¶
If you want to run Kinto with some core libraries under development (like Cornice),
just install them from your local folder using pip
.
For example:
cd ..
git clone https://github.com/mozilla-services/cornice.git
cd kinto/
.venv/bin/pip install -e ../cornice/
Run load tests¶
From the loadtests
folder:
make test SERVER_URL=http://localhost:8888
Run a particular type of action instead of random:
LOAD_ACTION=batch_create make test SERVER_URL=http://localhost:8888
(See loadtests source code for an exhaustive list of available actions and their respective randomness.)
Cleaning your environment¶
There are three levels of cleaning your environment:
make clean
will remove*.pyc
files and__pycache__
directory.make distclean
will also remove*.egg-info
files and*.egg
,build
anddist
directories.make maintainer-clean
will also remove the.tox
and the.venv
directories.
How to release¶
In order to prepare a new release, we are following the following steps.
The prerelease and postrelease commands are coming from zest.releaser.
Install zest.releaser with the recommended dependencies. They contain wheel and twine, which are required to release a new version.
$ pip install "zest.releaser[recommended]"
Step 1¶
$ git checkout -b prepare-X.Y.Z
$ prerelease
$ vim docs/conf.py
- Merge remaining pull requests
- Update
CHANGELOG.rst
- If API was updated, update API changelog in
docs/api/index.rst
- Make sure
HTTP_API_VERSION
is up-to-date in kinto/__init__.py`` - Update the link in
docs/configuration/production.rst
- Update
CONTRIBUTORS.rst
. The following hairy command will output the full list:
$ git shortlog -sne | awk '{$1=""; sub(" ", ""); print}' | awk -F'<' '!x[$1]++' | awk -F'<' '!x[$2]++' | sort
- Update known good versions of dependencies in
requirements.txt
with this command:
$ make build-requirements
- Open a pull-request to release the new version.
$ git commit -a --amend
$ git push origin prepare-X.Y.Z
Step 2¶
Once the pull-request is validated, merge it and do a release.
Use the release
command to invoke the setup.py
, which builds and uploads to PyPI
$ git checkout master
$ git merge --no-ff prepare-X.Y.Z
$ release
$ postrelease
Step 3¶
As a final step:
- Close the milestone in Github
- Create next milestone in Github in the case of a major release
- Add entry in Github release page
- Check that the version in ReadTheDocs is up-to-date
- Check that a Docker image was built
- Send mail to ML (If major release)
- Tweet about it!
Upgrade:
- Deploy new version on demo server
- Upgrade dependency in
kinto-dist
repo - Upgrade version targetted in
kinto-heroku
repo - Upgrade version of Kinto server for the tests of clients and plugins repos (kinto-http.js, kinto-http.py, kinto-attachment, etc.)
That’s all folks!