Code style is tested using flake8,
with the configuration set in .flake8,
and code formatted with black.
Installing with jupyter-cache[code_style] makes the pre-commit
package available, which will ensure this style is met before commits are submitted, by reformatting the code
and testing for lint errors.
It can be setup by:
>> cd jupyter-cache
>> pre-commit install
Optionally you can run black and flake8 separately:
>> black .
>> flake8 .
Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
All functions and class methods should be annotated with types and include a docstring. The prefered docstring format is outlined in jupyter-cache/docstring.fmt.mustache and can be used automatically with the
autodocstring VS Code extension.
For code tests:
>> cd jupyter-cache
For documentation build tests:
>> cd jupyter-cache/docs
>> make clean
>> make html-strict
To contribute, make Pull Requests to the master branch (this is the default branch). A PR can consist of one or multiple commits. Before you open a PR, make sure to clean up your commit history and create the commits that you think best divide up the total work as outlined above (use git rebase and git commit --amend). Ensure all commit messages clearly summarise the changes in the header and the problem that this commit is solving in the body.
git commit --amend
Merging pull requests: There are three ways of ‘merging’ pull requests on GitHub:
Squash and merge: take all commits, squash them into a single one and put it on top of the base branch.
Choose this for pull requests that address a single issue and are well represented by a single commit.
Make sure to clean the commit message (title & body)
Rebase and merge: take all commits and ‘recreate’ them on top of the base branch. All commits will be recreated with new hashes.
Choose this for pull requests that require more than a single commit.
Examples: PRs that contain multiple commits with individually significant changes; PRs that have commits from different authors (squashing commits would remove attribution)
Merge with merge commit: put all commits as they are on the base branch, with a merge commit on top
Choose for collaborative PRs with many commits. Here, the merge commit provides actual benefits.