Table of contents:
- Where to start?
- Getting Help
- Working with the code
- Contribute with code
- Contribute with documentation
- Send you changes to Fklearn repo
We love pull requests(and issues) from everyone. We recommend you to take a look at the project, follow the examples before contribute with code.
By participating in this project, you agree to abide by our code of conduct.
If you found a bug or need a new feature, you can submit an issue.
If you would like to chat with other contributors to fklearn, consider joining the Gitter.
Now that that you already understand how the project works, maybe it’s time to fix something, add and enhancement, or write new documentation. It’s time to understand how we send contributions.
This project is hosted in Github, this way, to contribute with it you need an account, you sign up here <https://github.com/signup/free>_ We use git as version control, so it’s good to understand basic git flows before send new code. You can follow Github Help to understand how to work with git.
To write new code, you will iteract with your own fork, so go to fklearn repo page, and hit the
Fork button. This will create a copy of our repository in your account. To clone the repository in your machine:
git clone email@example.com:your-username/fklearn.git git remote add upstream https://github.com/nubank/fklearn.git
This will create a folder called
fklearn and will connect to the upstream(main repo).
We recommend you to create a virtualenv before starts to work with the code. And be able to run all tests locally before start to write new code.
# Use an ENV_DIR of you choice. We are using ~/venvs python3.6 -m venv ~/venvs/fklearn-dev source ~/venvs/fklearn-dev/activate
This command will install all the test dependencies. To install the package itself follow install instruction.
pip install -qe .[test_deps]
The following command should run all tests, if every test pass, you should be ready to start develop new stuff
python -m pytest tests/
First we should check if you master is up to date with the latest version of the repo
git checkout master git pull upstream master --ff-only
git checkout -b name-of-your-bugfix-or-feature
If you already have a branch, and you want to update with the upstream master
git checkout name-of-your-bugfix-or-feature git fetch upstream git merge upstream/master
In this session we’ll guide you on how to contribute with the code. This is a guide if you want to fix or implement a new feature.
In order to check if your code follow our style, you can run from the repo root dir:
python -m pip install -q flake8 python -m flake8 \ --ignore=E731,W503 \ --filename=\*.py \ --exclude=__init__.py \ --show-source \ --statistics \ --max-line-length=120 \ src/ tests/
After you finish your feature development or bug fix, you should run your tests, using:
python -m pytest tests/
Or if want to run only one test:
python -m pytest tests/test-file-name.py::test_method_name
You should always write tests for your features, you can look at the other tests to have a better idea how we implement them. As test framework we use pytest
All methods should have type annotations, this allow us to know what that method expect as parameters, and what is the output. You can learn more about it in typing docs
To document your code you should add docstrings, all methods with docstring will appear in this documentation’s api file.
If you created a new file, you may need to add it to the
api.rst following the structure
Folder Name ----------- File name (fklearn.folder_name.file_name) ######################################### ..currentmodule:: fklearn.folder_name.file_name .. autosummary:: method_name The docstrings should follow this format .. code-block:: none """ Brief introduction of method More info about it Parameters ---------- parameter_1 : type Parameter description Returns ------- value_1 : type Value description """
You can add, fix documenation of: code(docstrings) or this documentation files.
This documentation is written using rst(
reStructuredText) you can learn more about it in rst docs
When you make changes in the docs, please make sure, we still be able to build it without any issue.
You should think about a commit as a unit of change. So it should describe a small change you did in the project.
The following command will list all files you changed:
To choose which files will be added to the commit:
git add path/to/the/file/name.extension
And to write a commit message:
This command will open your text editor to write commit messages
This will add a commit only with subject
git commit -m "My commit message"
We recommend this guide to write better commit messages
After you write all your commit messages, decribing what you did, it’s time to send to your remote repo.
git push origin name-of-your-bugfix-or-feature
Now that you already finished your job, you should:
- Go to your repo’s Github page
New pull request
- Choose the branch you want to merge
- Review the files that will be merged
Create pull request
- Fill the template
- Tag your PR, add the category(bug, enhancement, documentation…) and a review-request label
Use Semantic versioning to set library versions, more info: semver.org But basically this means:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
(from semver.org summary)
You don’t need to set the version in your PR, we’ll take care of this when we decide to release a new version. Today the process is:
- Create a new
milestoneX.Y.Z (maintainers only)
- Some PR/issues are attibuted to this new milestone
- Merge all the related PRs (maintainers only)
- Create a new PR:
Bump package to X.Y.ZThis PR update the version and the change log (maintainers only)
- Create a tag
This last step will trigger the CI to build the package and send the version to pypi
When we add new functionality, the past version will be moved to another branch. For example, if we’re at version 1.13.7 and a new functionality is implemented, we create a new branch 1.13.x, and protect it(this way we can’t delete it), the new code is merged to master branch, and them we create the tag 1.14.0
This way we can always fix a past version, opening PRs from 1.13.x branch.