Getting Started

Clone GoodSciProjTemplate’s GitHub repository:

$ git clone https://github.com/yoctoyotta1024/GoodSciProjTemplate.git

and then create an environment with the necessary dependencies installed (e.g. using micromamba, or conda as listed in the environment.yaml):

$ micromamba env create -f environment.yaml
$ micromamba activate goodsciproj_env

Finally install the pre-commit hooks:

$ pre-commit install

which will be used when you try to commit something or you execute pre-commit run. You can learn more about the powers of pre-commit from their documentation:.

That’s it, you’re done! But maybe now you want to customise the project and push it to your own GitHub repo…

Making the Project Your Own

Necessary first steps:

  1. Rename your GoodSciProjTemplate folder to the name of your project, e.g. mv GoodSciProjTemplate [project_name]

  2. Create an empty GitHub repository and set the remote url for your new project to it.

    1. delete git@github.com:yoctoyotta1024/GoodSciProjTemplate.git from your remote with git remote remove origin

    2. add your repository: git remote add origin [git@github.com:your_repository_ssh.git]

  3. Switch to a new branch (not main!):

    1. git switch -c [branch_name]

    2. and start customising the template… (hint: each of the following changes is a seperate commit. Remember to use coventional commit messages and don’t push to your remote branch until the end.)

  4. Make yourself the github.repository_owner who triggers GitHub’s CI to publish documentation (see .github/workflows/CI.yaml and .github/workflows/cocogitto.yaml).

  5. Make the project name yours instead of “GoodSciProjTemplate”.

  6. Make the citation and liscence refer to you instead of me.

  7. Write a new README.md (shorter is generally better) and include a link to your documentation in it.

  8. Correct the GitHub links (”https://github.com/…”) in the .rst files in the docs directory to the ones for your GitHub repository.

  9. Delete GoodSciProjTemplate’s CHANGELOG.md rm CHANGELOG.md.

  10. Delete any pre-existing tags and push a 0th version tag to your remote repository:

    1. git tag to see any pre-existing tags, then git tag -d [pre-existing_tags]

    2. git tag -a v0.0.0 -m "init repo

    3. git push --tags

  11. Setup (or delete) cocogitto (see Commit Messages and Versioning).

  12. Build (or delete) C++ code in the repository (see Python Bindings for C++).

  13. Push all your changes to a branch of your GitHub repository (not main!).

    1. git push --set-upstream origin [branch_name]

Necessary second steps:

  1. Create a pull request and accept it if your CI succeeds in order to to merge/rebase your changes to the main branch of your remote (GitHub) repository.

  2. Set your documentation to deploy using the /(root)/ folder of your gh-pages branch (see instructions for GitHub publishing).

Some suggested third steps:

  1. Make the release/version yours instead of “0.0.0”.

  2. Change the names of the C++ and Python package names in the libs directory (maybe you also prefer to call “libs” “src”?)

  3. If you made a C++ library, set your `INPUT` in doxygen.dox and your breathe_projects and/or default_breathe_projects in conf.py to match the name of the new C++ library.

  4. Make a new Python or C++ module/subpackage (include docstrings and write unit tests in the tests directory!).

  5. Create an associated .rst file for your new module/subpackage (somewhere in the docs/source directory).

  6. Add the path to your new .rst file to the contents of the .. toctree:: in index.rst.

  7. Push your changes to a branch of your GitHub repository (not main!).

  8. Create a pull request and accept it if your CI succeeds to merge your changes to the main branch of your remote (GitHub) repository.

  9. Be proud of your new code with documentation and tests!

Want more ideas?!

Have you thought about adding contributors, acknowledgements, more Python and/or other requirements/environments, more CI or pre-commit tasks, and an automatic file header generator? Maybe you’ve noticed this repository uses conventional commits to enable cocogitto’s automatic version control? Or maybe you should ponder all this over a cup of tea and some biscuits…

A Note on Commiting Large Files:

This project forbids you from commiting and pushing large files such as Jupyter notebooks (.ipynb files) and images (e.g. .png files) to your repository. Such actions are highly discouraged and usually a sign that you are doing something wrong. If you want to use Jupyter notebooks, consider using the Jupyter Book extension of Sphinx to store your notebooks as markdown files. At the very least, you should scrub notebooks before committing them because you do not want to destory the power of git diff by making it start comparing Jupyter notebook hashes.

A Standard Git + GitHub Workflow

Always keep your local main branch up to date with its remote version! Everytime you start work, you should perform git switch main then git pull (or git fetch and git merge).

  1. Before you start making any change to your repo, you should first branch off your main branch:

    1. git switch main

    2. git switch -c [branch_name]

  2. Make the changes you want and stage them with:

    1. git add -p (accept / decline changes)

  3. Commit your changes (frequently!!) with:

    1. git commit -m "<type>[optional scope]: <description>"

    2. See conventional commit guidelines for writing good commit messages

  4. Push your changes to your remote repository with git push.

  5. Create a pull request to merge/rebase your changes to your remote main branch.

  6. Delete your local (and remote) branch after your pull request is accepted:

    1. git branch -d [branch_name]

  7. Start a new branch from main to make further changes.

If you happen to be working on a branch at the same time that changes to the main branch occur, make sure to keep your branch up-to-date! The more your branch differs from main, the more likely you will encounter merge conflicts (not fun!). Keep your branches up to date by keeping your local main branch up-to-date and then keeping your branches up-to-date with your local main branch. E.g.

  1. git switch main then git pull

  2. git switch [branch_name] then git rebase main