Skip to content

Commit

Permalink
Merge pull request #5 from kordejong/gh4
Browse files Browse the repository at this point in the history
Create initial version
kordejong authored Jul 15, 2024
2 parents 2037940 + d146d12 commit b41ad7b
Showing 11 changed files with 131 additions and 39 deletions.
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@ cmake_minimum_required(
VERSION 3.26)
project(Ruminations
LANGUAGES NONE
VERSION 0.0.1
VERSION 0.1.0
DESCRIPTION "Ruminations on setting up and maintaining model development projects"
HOMEPAGE_URL "https://github.com/computationalgeography/ruminations"
)
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -5,6 +5,7 @@ An opinionated view on setting up and maintaining model development projects.
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r environment/configuration/requirements.txt
```

```bash
@@ -13,3 +14,7 @@ mkdir build
cd build
cmake ..
```

```bash
environment/script/serve_documentation.py $RUMINATIONS $RUMINATIONS_OBJECTS
```
2 changes: 1 addition & 1 deletion documentation/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -9,7 +9,7 @@ foreach(name IN ITEMS
changelog.md
code.md
dependencies.md
introduction.md
index.md
python.md
references.bib
repository.md
2 changes: 1 addition & 1 deletion documentation/_config.yml.in
Original file line number Diff line number Diff line change
@@ -23,7 +23,7 @@ bibtex_bibfiles:
# Information about where the book exists on the web
repository:
url: @CMAKE_PROJECT_HOMEPAGE_URL@
path_to_book: doc # Optional path to your book, relative to the repository root
# path_to_book: doc # Optional path to your book, relative to the repository root
branch: main # Which branch of the repository should be used when creating links (optional)

# Add GitHub buttons to your book
2 changes: 1 addition & 1 deletion documentation/_toc.yml
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@
# Learn more at https://jupyterbook.org/customize/toc.html

format: jb-book
root: introduction
root: index
chapters:
- file: repository
- file: dependencies
4 changes: 4 additions & 0 deletions documentation/changelog.md
Original file line number Diff line number Diff line change
@@ -2,5 +2,9 @@

Description of all notable changes made per revision.

# 0.1.0
- Initial version of [repository chapter](#repo).


# 0.0.1
- Initial version.
14 changes: 14 additions & 0 deletions documentation/code.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,17 @@
# Code

:::{epigraph}
A complex system that works is invariably found to have evolved from a simple system that worked. A complex
system designed from scratch never works and cannot be patched up to make it work. You have to start over with
a working simple system.

-- [John Gall](https://en.wikipedia.org/wiki/John_Gall_(author))
:::

Topics related to code in general, not specific for Python.


(code-simple)=
## Write simple code

TODO
4 changes: 3 additions & 1 deletion documentation/dependencies.md
Original file line number Diff line number Diff line change
@@ -26,7 +26,7 @@ install cmake`).

See also:

- TODO Link to CMake home
- [cmake.org](https://cmake.org)
- [](#deps-generate-documentation)
- [](#deps-separate-source-build)

@@ -36,6 +36,8 @@ See also:

TODO

- [sphinx-doc.org](https://www.sphinx-doc.org)


(deps-separate-source-build)=
## Put generated files in a separate directory
29 changes: 18 additions & 11 deletions documentation/introduction.md → documentation/index.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
# Introduction

:::{warning}
This document is still very much work in progress. You will find lots of TODOs here. Please come back
later, after we have filled in some more blanks.
:::

In this document we provide guidelines for setting up and maintaining a model development project. It is
targeted at model developers who are not also experienced software developers, for example domain experts who
develop models part-time.
targeted at model developers who are not also experienced software developers, but for example domain experts
who develop models part-time.

We assume that you use Git to manage versions of your model's source files, and that you use Python as the
programming language for implementing the model. In this document you will not find information about why to
use Git or Python, nor is it an introduction to them. You probably already know at least the basics, maybe
because you followed a course.

Here, you will find information that is a bit harder to find, for example because it is hidden in
books you may never read because they are about the practice of software development in general, or because it
requires more experience than you may have.
Here, you will find information that is a bit harder to find, for example because it is hidden in books you
may never read because they are about the practice of software development in general, or because it requires
more experience than you may have.

:::{margin} GTD
You may have heard of the book called [Getting Things
@@ -22,16 +28,16 @@ have the same result, but in the domain of model development using Python.

To illustrate the gap we are trying to fill, assume asking 10 domain experts to implement a certain model and
provide you with the end result. It is very likely that you will end up with 10 different sets of files with
different contents. The layout of the repository will be different, as will the names of the files, the design
different contents. The layout of the repositories will be different, as will the names of the files, the design
of the code, the layout of the code, the naming conventions used in the code, etc. Why is this the case?
Because each model developer individually makes decisions about these matters while implementing their model,
based on their preference, experience and the set of tools they use. The problem with this is that it makes it
harder than necessary to collaborate with each other. Using similar conventions and coding practices make it
harder than necessary to collaborate with each other. Using similar conventions and coding practices makes it
easier for us all to understand each other's code. For some of the conventions and practices good guidelines
exist. We think it is a good thing if model developers know about these, hence this document.
exist. We think it is a good thing when model developers know about these, hence this document.

:::{note}
You likely don't agree with every guideline we provide, and for good reasons. Use the ones you think are
You may not agree with every guideline we provide, and maybe for good reasons. Use the ones you think are
useful.
:::

@@ -41,5 +47,6 @@ dependencies, add Python code. There is no need to read things in order, so you
interests you. We have added links between related topics.

This document will change over time, as we improve existing guidelines and include new ones. We invite you to
help with this by suggesting better ways to describe guidelines and suggesting new ones. In case you are
really inspired then please fork the repository, make improvements, and submit a pull request.
help with this by suggesting better ways to describe guidelines and suggesting new ones, for example. In case
you are really inspired then please fork the repository, make improvements, and submit a pull request
([](#repo-fork-contribute)).
6 changes: 4 additions & 2 deletions documentation/python.md
Original file line number Diff line number Diff line change
@@ -9,6 +9,8 @@ Topics related to using Python for model development.

TODO

- [github.com/conda-forge/miniforge](https://github.com/conda-forge/miniforge)


(py-black)=
## Use Black
@@ -20,7 +22,7 @@ each time you change them.

See also:

- Link to Black
- [black.readthedocs.io](https://black.readthedocs.io)
- [](#py-mypy)
- [](#repo-pre-commit)

@@ -32,6 +34,6 @@ TODO

See also:

- Link to Mypy
- [mypy-lang.org](https://mypy-lang.org/)
- [](#py-black)
- [](#repo-pre-commit)
100 changes: 79 additions & 21 deletions documentation/repository.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
(repo)=
# Repository

Topics related to a project's Git repository.
@@ -12,23 +13,26 @@ Synchronizing all your work with a Git repository on a server has several advant
- You can more easily work on your project on different platforms (laptop, desktop, ...)
- You can collaborate with colleagues

:::{note}
GiHub is not Git and Git is not GitHub. GitHub is a popular way for managing Git repositories and provides
many useful tools for collaborating on a project. Gitlab does something similar in a slightly different way.
More options exist, like Codeberg and Gitea, and it is also possible to setup a Git server yourself.
:::{margin} GitHub vs Git
GiHub is not Git and Git is not GitHub. GitHub is a [forge](https://en.wikipedia.org/wiki/Forge_(software)).
Other forges exist as well, like Forgejo, Gitea, and GitLab. Some of these forges can also be self-hosted.
:::

See also:

- [](#repo-small-changes)


(repo-organize)=
## Organize repositories by platform and grouping construct
## Organize repositories by host name and grouping construct

Before you know it, you will have multiple Git repositories cloned on your computer. You need to decide on a
way to organize these. One option is to organize them first by platform (like `github` in case of GitHub), and
then by grouping construct as used on the platform (like the organization on GitHub). This way, repositories
with the same name but in different organizations, like a fork for example, will end up in a unique location
in the file system.
way to organize these. One option is to organize them first by host name (like `github` in case of GitHub),
and then by grouping construct as used on the hosted forge (like the organization on GitHub). This way,
repositories with the same name but in different organizations, like a fork for example, will end up in a
unique location in the file system.

Example file system tree of directories with Git repositories from different platforms:
Example file system tree of directories with Git repositories from different forges:

```
project/
@@ -42,6 +46,9 @@ project/
faculty/
department/
cool_package/
my_own_server/
personal/
snippets/
```

See also:
@@ -62,16 +69,16 @@ files, large files, and files with different line endings, but also spelling err
messages, and documentation.

There are tools that you can run to check whether files adhere to certain rules, like the code's formatting
style, for example. Some of these tools even fix any deviations from the "correct" style. Running these tools
each time you have made a change quickly becomes a hassle.
style, for example. Some of these tools can even automatically fix any deviations from the "correct" style.
Such tools can be very useful, but running them each time you have made a change quickly becomes a hassle.

Pre-commit helps you to automatically run tools that check and fix changes made to your repository every time
you want to commit these changes. On the website you can find a repository of easy to use hooks which you can
refer to from the Pre-commit configuration file.

See also:

- TODO link to pre-commit
- [pre-commit.com](https://pre-commit.com)
- [](#deps-separate-source-build)
- [](#py-black)
- [](#py-mypy)
@@ -80,20 +87,37 @@ See also:
(repo-small-changes)=
## Make small changes

TODO
Working on and finishing relatively small tasks has several advantages:

- It decreases the chance of loosing uncommitted work, due to a hardware failure for example
- It will make it easier to work on different tasks concurrently, either by yourself or by team members.
Rebasing ongoing work on a huge commit increases the chance of merge conflicts you have to resolve.
- It will be easier to perform "code archaeology", to figure out what changed when a specific feature was
introduced, for example
- It will give you a nice feeling of making progress

See also:

- [](#repo-remote)
- [](#repo-issue-per-change)
- [](#repo-changes-in-branch)


(repo-issue-per-change)=
## Create an issue per change
## Create an issue / ticket per change

TODO
An issue is a single piece of work that will improve the code, like a new feature or a bug fix.

This has several advantages:

- It makes it easier to plan releases by associating specific issues that should be solved for each release
- It will be easier to collaborate. Focussed tasks often require a smaller set of skills, increasing the
chance that someone wanting to contribute has these.
- It will make it easier to work on different tasks concurrently, either by yourself or by team members.

See also:

- [](#repo-small-changes)
- [](#repo-name-branch)


@@ -130,7 +154,37 @@ See also:
(repo-merge-bubbles)=
## Use merge bubbles when merging branches

TODO
A merge bubble results from merging a branch and creating a merge commit. A merge commit has two branches as a
parent: the branch merged and the branch merged into. In general these are a topic branch and the main branch,
respectively.

Merge bubbles make it convenient to visually inspect which commits are part of a branch, for example using
this command:

```bash
git log --oneline --decorate --graph
* 3ada53d Update deploy.yml
* b444544 Merge pull request #1 from computationalgeography/upstream/main
|\
| * cbe713b Add deploy workflow
| * a01095e WIP
| * b422ffb Update documentation
| * dba8cd2 WIP
| * 0f84642 WIP
| * fb9b4bd WIP
| * 484ace3 Setup project
|/
* 9ac4878 Initial commit
```

Here is an example of merging a topic branch and creating a merge bubble. The relevant option is `--no-ff`.

```bash
git checkout main
git merge --no-ff gh123
git push
git branch -d gh123
```


(repo-fork-contribute)=
@@ -140,9 +194,9 @@ If you want to contribute to someone else's repository, to which you do not have
fork the project first. You can then make changes within a branch of the copy of the original repository. Once
finished, you can submit a pull request to the original repository, based on your branch.

This process also works for your own repository, to which you do have write permissions. To keep things
simple, and to understand what people contributing to your repository have to go through, you can use this way
of contributing to a repository in all cases.
This process also works for your own repository, to which you actually do have write permissions. To keep
things simple, and to understand what people contributing to your repository have to go through, you can use
this way of contributing to a repository in all cases.

Example workflow in case of GitHub:

@@ -179,7 +233,7 @@ To keep your copy of the repository (AKA downstream repository) up-to-date with
```bash
# Update your version of upstream's main branch
git checkout main
git pull upstream main
git pull --rebase upstream main
git push

# Rebase your work on updated main branch
@@ -188,6 +242,10 @@ To keep your copy of the repository (AKA downstream repository) up-to-date with
git push
```

:::{warning}
Except from merging updates from upstream's main branch, don't commit other updates to your version of
upstream's main branch. You want to keep both main branches identical.
:::

See also:

0 comments on commit b41ad7b

Please sign in to comment.