Getting up and running requires a short process.

You will need the following:
  • Python 3.8+

  • The cookiecutter tool installed

  • A GitHub account

1. Use the cookiecutter to create a new project

An example of using the cookiecutter is illustrated below. The first line is the prompt, i.e. the actual command to use. It is followed by all the prompts you can expect, and some example answers.

$ cookiecutter gh:MDAnalysis/cookiecutter-mdakit
  [1/11] project_name (ProjectName): My Project Name
  [2/11] repo_name (my_project_name): example-repository
  [3/11] package_name (example_repository): package_name
  [4/11] description (A short description of the project.): A package to do MD analysis
  [5/11] github_username (Your personal GitHub username): my-github-username
  [6/11] github_host_account (GitHub account for hosting example-repository 
(e.g. my-github-username or an organization account). Press Enter to use 
  [7/11] author_name (Your name (or your organization/company/team)): My Name
  [8/11] author_email (Your email (or your organization/company/team)):
  [9/11] Select dependency_source
    1 - Prefer conda-forge over the default anaconda channel with pip fallback
    2 - Prefer default anaconda channel with pip fallback
    3 - Dependencies from pip only (no conda)
    Choose from [1/2/3] (1): 
  [10/11] Select include_ReadTheDocs
    1 - y
    2 - n
    Choose from [1/2] (1): 
  [11/11] template_analysis_class (Class name to template (e.g. MyProjectName ).
Press Enter to skip including analysis templates): MyAnalysisClass

This generates the output skeleton:

├── .codecov.yml                              <- Settings for Codecov
├── .gitattributes                         
├── .github                                   <- GitHub hooks for user contribution, pull request guides and GitHub Actions CI
│   ├── ISSUE_TEMPLATE                        <- Templates for opening issues on GitHub
│   │   ├──                  
│   │   └──             
│   ├──              <- Template for opening a pull request on GitHub
│   └── workflows                             <- where the configuration for CI lives
│       └── gh-ci.yaml                     
├── .gitignore                                <- Stock helper file telling git what file name patterns to ignore when adding files
├── .pre-commit-config.yaml                   <- Settings for pre-commit hooks for flake8 and isort
├── .pylintrc                                 <- Settings for PyLint
├──                                <- List of all contributors to the package
├──                              <- Log of changes in each release
├──                        <- Code of Conduct for developers and users
├──                           <- Guide to contributing
├── LICENSE                                   <- License file
├──                               <- Packaging information for pip
├──                                 <- Description of project which GitHub will render
├── devtools                                  <- Environment and other development tools
│   └── conda-envs                            <- Conda environments for testing
│       └── test_env.yaml                     <- Default test environment file
├── docs                                      <- Documentation template folder with many settings already filled in
│   ├── Makefile                           
│   ├──                             <- Instructions on how to build the docs
│   ├── make.bat                           
│   ├── requirements.yaml                     <- Documentation building specific requirements. Usually a smaller set than the main program
│   └── source                             
│       ├── _static                        
│       │   ├──                  
│       │   └── logo                       
│       │       ├── placeholder_favicon.svg
│       │       └── placeholder_logo.png   
│       ├── _templates                     
│       │   └──                  
│       ├── api.rst                        
│       ├──                        
│       ├── getting_started.rst            
│       └── index.rst                      
├── package_name                           
│   ├──                        
│   ├── analysis                           
│   │   ├──                    
│   │   └──             
│   ├── data                                  <- Sample additional data (non-code) which can be packaged
│   │   ├──                      
│   │   ├──                    
│   │   ├──                          <- Recommended file for resolving data file names
│   │   └── mda.txt                           <- Just an example, delete in production
│   └── tests                                 <- Unit test directory with sample tests
│       ├──                    
│       ├── analysis                       
│       │   ├──                
│       │   └──    
│       ├──                       <- File for common pytest fixtures
│       ├──              <- Example test file
│       └──                       
├── pyproject.toml                            <- Dependencies for pip
└── readthedocs.yaml                          <- Settings for ReadTheDocs
16 directories, 44 files                   

We will go more into these files in the rest of this tutorial, as well as other sections in this documentation. Please see Options for more details.

2. Add the project to GitHub

The generated repository should be an initialised git repository. We now need to connect it to GitHub:

  1. Create a new repository on GitHub . Do not initialize the repo with a README, license, or any other files.

  2. Push the local repository to GitHub. GitHub should provide instructions for doing so, but in short:

    • Add the remote named origin with 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 main branch 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 release. The cookiecutter uses versioningit to automatically determine your package’s version based on git tags.

By default, versioning will start from 0.0.0. You can install versioningit to check the current versioningit output from commandline:

$ cd <my_package_directory>
$ versioningit .

As you add commits, the versioning will automatically update with the commit hashes:

$ versioningit .

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 .