Contributing

Contributing#

This project is a collaborative team effort, and we want to make contributing as easy as possible. This page provides a small workthrough for contributing to the IOER FDZ Geospatial Training Materials. Please note that you currently need to request access in order to participate. Please contact the IOER team.

Mountain picture Made with❤️, Collaboration, and Open Source Software. Picture: 2021 Alexander Dunkel

Table of Contents

1. Overview of files
2. Publishing process
3. Editing files
4. Jupyter Collaborative Editing
5. Git best practices
6. Semantic Versioning
7. Formatting conventions
8. Citations, references

1. Overview of files#

All documents are edited as Jupyter notebooks and can be found in the subfolder notebooks/, e.g.:

2. Publishing process#

Files are stored in this git repository. When changes are made to the notebook files, an automation is triggered to update the website at https://training.fdz.ioer.info (git branch main) and https://stag.training.fdz.ioer.info/ (git branch staging).

These two sites help to incrementally improve the training materials:

https://stag.training.fdz.ioer.info/ - always up-to-date, see documentation changes immediately. This page is only visible from the IOER Intranet
https://training.fdz.ioer.info - a “production” version that looks more polished; changes from the staging branch are selectively merged in. This page is publicly visible

Start working on the staging branch. We pull changes that are ready into the main (production) branch.

The process for a single notebook change: diagram

3. Editing files#

You can edit these files from anywhere. However, depending on your knowledge of git, we suggest one of the following:

Request access to the Gitlab Chemnitz

For IOER-Internal use only: In order to participate, request access to the Gitlab Chemnitz Group.

Use a common Jupyter Server for collaborative editing and follow the steps outlined under 4: Jupyter Collaborative Editing.
Edit files directly in the Gitlab Repository
Clone the repository locally and edit the Jupyter notebook files directly using your preferred environment. Only use this option if you are familiar with git!

4. Jupyter Collaborative Editing#

Join a collaborative Jupyter session in your browser.

4.1 Start with editing a Jupyter notebook#

_images/01_edit_files.gif — Fig. 19 Start with editing a Jupyter notebook.#

Save changes to the notebook file with CTRL+S.

4.2 Open the Jupyter git extension#

_images/02_git_extension.gif — Fig. 20 Find the JupyterLab Git extension.#

Note that we are on the git branch called staging. We can also see that the notebook 01_introduction.ipynb has changes that are not yet commited.

4.3 Commit changes#

_images/03_stage_changes.gif — Fig. 21 “Staging” changes#

For all changed files you want to update, click the + icon. This is called staging in git.

4.4 Write a commit message#

_images/04_commit_message.gif — Fig. 22 Write a commit message.#

Write a short description of what the changes are, then click commit. You may be asked to enter your name and email once.

4.5 Push changes to remote#

If you see an orange dot next to the left icon, click to first pull changes:

_images/05_pull_changes.gif — Fig. 23 Click on “Pull changes from remote”#

_images/06_push_changes.gif — Fig. 24 Click on “Push changes to remote”.#

4.6 Wait for the website to update#

Head to https://gitlab.hrz.tu-chemnitz.de/ioer/fdz/jupyter-book-nfdi4biodiversity/-/pipelines and wait until the Continuous Integration pipeline finished updating the website.

This will take about 1-2 Minutes.

_images/07_ci_pipeline.webp — Fig. 25 A passed pipeline with two stages (green checkmarks).#

Once you see two green checkmarks, open the staging website and have a look at the updated website.

https://stag.training.fdz.ioer.info/

_images/08_observe_changes.gif — Fig. 26 The rendered training materials with the changed text.#

5. Git best practices#

Commit often. After any change, commit changes and push to remote. This also ensures your data is backed up and always up to date.
When you start your day, always pull the latest changes from remote first. This ensures that you have the latest version locally and do not have to merge past changes later.
If you want to maintain your work in progress, it is possible to store copies of notebooks under tmp/ folder. Changes in this folder are ignored. Once you are happy with your progress, manually copy & paste cells or content to the original notebook files, to commit these changes.

6. Semantic Versioning#

The book is automatically versioned using the python-semantic-release. It follows the Semantic Version Specification (MAJOR.MINOR.PATCH). Please follow the Conventional Commits Specification for writing your commit messages (see also Semantic Commit Message Conventions). Our continuous integration will pick up commit messages, bump versions accordingly, and update the Changelog.

Since these training materials consists of a mixture of code, comments, documentation and results, we suggest to follow the below examples.

Documentation, descriptions or any code comments changed#

Use:

docs: improved description of chapter 1

The same applies to minor changes such as fixing typos: Use:

docs: fixed typo

These changes will not result in any version bump, but they will be listed as improvements under Documentation in the next release.

Minor code changes, bug fixes#

Use:

fix: issue with matplotlib and legend in figure 7

This will result in a new patch release.

Significant code changes, larger changes to the book structure#

Use:

feat: added an interactive map (folium) to chapter 7

This will result in a new minor release.

Changes to the Continuous Integration#

Use:

ci: fix registry image not accessible

These changes will not result in any version bump, but they will be listed as improvements under Continuous Integration in the next release.

Other commit messages#

There are a number of other message types, such as refactor, style, (etc.). All of these will not cause a version bump and can be used if and can be used if it fits.

7. Formatting conventions#

We want to make sure that we systematically reuse certain visual elements in the training materials. This is a collection of agreed style conventions.

General conventions are:

Use short sentences. As a guide, use no more than 10 to 15 words.
Use the .webp format for figures. Irfanview with plugins comes with webp support, so it is easy to capture and save webp files.

Check language and spelling (DeepL/Grammarly check)#

Words convey meaning, so it is best to use simple and easy to understand sentences. Tools like Grammarly or Linguee DeepL can help with this. Be sure to use American English for training materials.

_images/linguee.webp — Fig. 27 Linguee DeepL Grammar Check.#

Figure and Table formatting#

See the Jupyter Book docs on how to create Figures and Tables with caption.

There is a box-shadow effect shown around figures by default. If you want to disable this on selected graphics, add :figclass: fig-no-shadow to the {figure}-tag.

Like so

```{figure} ../resources/data-processing.png
:name: gbif-graphic
:figclass: fig-no-shadow

GBIF Data Processing Documentation 
```

Cross-refererences#

In order to not break cross-references, whenever using those, add an explicit cross-references anchor. These will stay the same even if headers (etc.) change:

(content:references:explitanchor)=
## Reference section labels

Then use the anchor to create a cross-reference

[Link Text](content:references:explitanchor)

See the docs

Requires user action (attention call)#

Our goal is to make the training material interactive. The user can change certain parts of the code and this will affect the results of further processing.

To highlight where the user can make these changes, we use callouts (admonitions) with the attention flag. These callouts are highlighted in orange. Below is an example that uses a dropdown in addition to the attention to further pique the user’s curiosity.

See example

```{admonition} Use your own common name!
:class: dropdown, attention
Optionally replace "English Sparrow" with another location above
```

See in action.

Admonitions#

Admonitions can ease reading flows by highlighting certain paragraphs differently.

_images/admonition.webp — Fig. 28 Two admonitions (with the drop-down feature enabled).#

In Markdown, formatting looks like this:

:::{note}
Callout Text
:::

Tip

It is up to you whether you use ::: or ```.

If you want to further replace the title:

```{admonition} Use your own title
:class: note
Callout Text
```

The full list of available admonitions can be found in the sphinx-docs.

The use of admonitions sometimes requires to nest different outputs. For example, maybe you want to show a code block inside an admonition. In this case, adding backticks (`) to the outer block need to be used.

See example

````{admonition} Use your own common name!
:class: dropdown, attention
Optionally replace "English Sparrow" with another location above
```python
# code block
```
````

In other cases, you may want to show images or other output rendered in a cell inside admonitions (e.g.). This is done with the glue-directive. See the Jupyter book docs. There is also an example in the file 202_data_retrieval.ipynb, see the result here.

Overview first, details on demand#

Overview first, details on demand (Schneiderman’s Mantra): Admonitions with drop-down are a good way to hide too much information in Markdown cells.

Another way to hide information in input and output cells are cell tags.

For example, to hide a long cell output, add hide-output to cell metadata. You can find cell metadata on the upper-right corner in Jupyter.

_images/hide-tag.webp — Fig. 29 Add `hide-output` to a cell’s metadata to hide its output with a drop-down link.#

8. Citations, references#

Citations are managed with sphinxcontrib-bibtex. See the Jupyter Book docs here.

1. Add bib-metadata

In order to add literature, first add the reference (*.bib format) to references.bib file in the root or the repository.

How to get the bib format?

You can sometimes download *.bib-metadata as “citations” from publication pages. Otherwise, use e.g. Zotero to export the publication to a *.bib file, open it, and copy the contents to references.bib.

2. Get reference

Your newly added bib-entry has a unique identifier, e.g. dworczyk_replication_2025. Memorize this reference.

3. Use reference

Depending on how you want to use the reference, these are some examples:

{cite:ts}`salek_house_2015`

will be rendered as (full author list, without et al.):

Šálek, Riegert, and Grill (2015)

{cite:t}`fischer_2023_10377868`

will be rendered as (in-text):

Fischer et al. (2023).

The **F**indable **A**cessible **I**nteroperable **R**eusable (**FAIR**) principles *({cite:alp}`wilkinson_fair_2016`)*

will be rendered as (no parenthesis)

The Findable Acessible Interoperable Reusable (FAIR) principles (Wilkinson *et al.* 2016)

4. Add a chapter bibliography

If you want to show a list of references used at the end of each notebook, add the follow to the last cell of your notebook:

## References

```{bibliography}
:style: unsrt
:filter: docname in docnames
```

5. Add a global bibliography

Create a new file BIBLIOGRAPHY.md and add:

# Bibliography

```{bibliography} references.bib
:style: plain
```

Link this file in the _toc.yml. This will list all references used throughout your book.