Getting up and running requires a short process.
- You will need the following:
The cookiecutter tool installed
A GitHub account
2. Add the project to GitHub
The generated repository should be an initialised git repository. We now need to connect it to GitHub:
Create a new repository on GitHub . Do not initialize the repo with a README, license, or any other files.
Push the local repository to GitHub. GitHub should provide instructions for doing so, but in short:
Add the remote named
git remote add origin <URL>
Push the local repository to the remote repository with
git push -u origin main
Verify files were pushed successfully by checking on GitHub
4. Make and push changes to your code
Now you should go forth and code! To keep things clean and simple, we advise a few tips:
Always work in a virtual environment like
conda. You can create a development environment by following the instructions in the README. In short:
conda create --name <environment_name> python=3.8 conda activate <environment_name> # remember to do this every time conda env update --name <environment_name> --file devtools/conda-envs/test_env.yaml conda env update --name <environment_name> --file docs/requirements.yaml
Always work in a separate branch. The
mainbranch is the default, or central, branch. All development work should be done in a separate branch to avoid messing up the main branch, or to allow you to work on different approaches at the same time. This also allows multiple people to work on the code at the same time. Create a new branch with
git checkout -b <my_branch_name>. See GitHub’s documentation on branches for more information.
When you feel ready, open a pull request on GitHub. This does not have to be when you think you have finished the code! A PR runs tests and builds documentation. This will allow others to review your code and help you make sure it is correct. It’s always a good way to get feedback and validation, as well as collaborate with other people. See GitHub’s documentation on PRs for more information.
5. Tagging versions of your code
Tagging versions of your code is a good way to keep references
to specific versions of your code that don’t change.
This is especially useful when you want to make a new code
cookiecutter uses versioningit to
automatically determine your package’s version based on
By default, versioning will start from
You can install versioningit to check the current versioningit output from commandline:
$ cd <my_package_directory> $ versioningit . 0.0.0
As you add commits, the versioning will automatically update with the commit hashes:
$ versioningit . 0.0.0+1.g58bcaff
To tag a version, use the following command:
git tag -a 0.1.0 -m "Version 0.1.0"
This will create a tag called
0.1.0 with the message
“Version 0.1.0”. You can then push this tag to GitHub with
git push origin --tags.
After creating a tag, you can check the versioning again:
$ versioningit . 0.1.0