Contributing to n2khab

First of all, thanks for considering contributing to n2khab! 👍 It’s people like you that make it rewarding for us - the project maintainers - to work on n2khab. 😊

n2khab is an open source project, maintained by people who care. We are not directly funded to do so.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

How you can contribute

There are several ways you can contribute to this project. If you want to know more about why and how to contribute to open source projects like this one, see this Open Source Guide.

Share the love ❤️

Think n2khab is useful? Let others discover it, by telling them in person, via Twitter or a blog post.

Using n2khab for a paper you are writing? Consider citing it.

# with the n2khab package installed, this will return a bibliography entry:
citation("n2khab")

Ask a question ⁉️

Using n2khab and got stuck? Browse the documentation to see if you can find a solution. Still stuck? Post your question as an issue on GitHub. While we cannot offer user support, we’ll try to do our best to address it, as questions often lead to better documentation or the discovery of bugs.

Want to ask a question in private? Contact the package maintainer by email.

Propose an idea 💡

Have an idea for a new n2khab feature? Take a look at the documentation and issue list to see if it isn’t included or suggested yet. If not, suggest your idea as an issue on GitHub. While we can’t promise to implement your idea, it helps to:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible.

See below if you want to contribute code for your idea as well.

Report a bug 🐛

Using n2khab and discovered a bug? That’s annoying! Don’t let others have the same experience and report it as an issue on GitHub so we can fix it. A good bug report makes it easier for us to do so, so please include:

  • Your operating system name and version (e.g. Mac OS 10.13.6).
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Help yourself and those you are asking for help: use the reprex package! Usually just running reprex::reprex(session_info = TRUE) on a small reproducible example will do all the magic. 🌟

Improve the documentation 📖

Noticed a typo on the website? Think a function could use a better example? Good documentation makes all the difference, so your help to improve it is very welcome!

The website

This website is generated with pkgdown. That means we don’t have to write any html: content is pulled together from documentation in the code, vignettes, Markdown files, the package DESCRIPTION and _pkgdown.yml settings. If you know your way around pkgdown, you can propose a file change to improve documentation. If not, report an issue and we can point you in the right direction.

Function documentation

Functions are described as comments near their code and translated to documentation using roxygen2. If you want to improve a function description:

  1. Go to R/ directory in the code repository.
  2. Look for the file with the name of the function.
  3. Propose a file change to update the function documentation in the roxygen comments (starting with #').

Contribute code 📝

Care to fix bugs or implement new functionality for n2khab? Awesome! 👏 Have a look at the issue list and leave a comment on the things you want to work on. See also the development guidelines below.

Development guidelines

Find your way: repository structure

This is the structure of the repo:

├── inst
│   └── textdata        <- Textual data delivered with the package (in vc-format).
│                          They can be read into R by package functions or with
│                          git2rdata::read_vc().
├── man                 <- Don't change this manually, it will be overwritten.
├── misc                <- Package-related scripts / R markdown files. Rbuild-ignored!
│                          Contains a script on package management + a bookdown 
│                          project to reproduce the included textual data + a 
│                          script to upgrade vc-formatted files.
├── R                   <- Package functions are to be made here.
├── vignettes           <- Vignettes are to be made here.
├── .github             <- Includes this guide, the code of conduct and configuration
│                          files for automated code management.
├── DESCRIPTION
├── LICENSE
├── n2khab.Rproj        <- Main RStudio project file.
├── NAMESPACE
├── NEWS.md             <- The changelog.
└── README.md           <- The package homepage.

Coding tools

When writing functions for n2khab:

  • please use sf and terra packages for reading geospatial data. Organise data in R in a tidy way in order to avoid troubles later on. Recommended resources to get started are:
  • have a quick look at the tidyverse style guide. There you see how to style object, variable and function names, as well as the documentation. At least keep in mind: use lower case and ‘snake_case’ for object, variable and function names.
  • if your function returns a data frame, use dplyr::as_tibble() to return it as a tibble instead. A tibble is a data frame that makes working in the tidyverse a little easier.
  • functions that read or process data should return data as much as possible internationalized:
    • availability of English names for types, environmental pressures, … Other languages can be accommodated as well;
    • English names for table headings (data frame variables).

How to contribute code?

Without write permissions to the code repository

We try to follow the GitHub flow for development.

  1. Fork this repo and clone it to your computer. To learn more about this process, see this guide.
  2. If you have forked and cloned the project before and it has been a while since you worked on it, pull changes from the original repo to your clone by using git pull upstream main.
  3. Open the RStudio project file (.Rproj).
  4. Make your changes:
    • Write your code.
    • Test your code (bonus points for adding unit tests).
    • Document your code (see function documentation above).
    • Do an R CMD check using devtools::check() and aim for 0 errors and warnings.
  5. Commit and push your changes.
  6. Submit a pull request.

With write permissions to the code repository

It is wise to first think about the scope of your function (or your proposed enhancement of an existing one), and talk it through with other collaborators:

  • functions that are of broader interest than Natura 2000, better go to inborutils or a separate package;
  • functions that will only be relevant to a specific N2KHAB project, are better developed in the project-specific repo.

You will want to look at the file src/manage_package.R to get some useful packaging commands and developing tips.

Releases, version numbering and the relation to git branches

  • We follow the semantic version numbering as described here.
  • The commit referred to by main (branch tip) must always have a <major>.<minor>.<patch> version number in the DESCRIPTION file. It is the latest released package version.
    • Subsequent commits on main which do not change the package code itself, but only website setup and repo documentation, must inherit the same release version number.
    • Commits which do change the package must carry a development version number; typically <major>.<minor>.<patch>.9000. It follows that they never appear at the tip of the main branch. Non-package commits may follow this route as well: it is safe for all new commits.
    These conventions ensure that:
    • a simple package installation with remotes::install_github(), which defaults to downloading from the main branch, will result in an installation of the latest release;
    • the pkgdown website shows the version number of the latest release.
  • Other branches than main can have various names. However, there is always at least one development branch whose name begins with dev. For example: dev_nextrelease, dev_0.4.0, … It is the collector of new features and bugfixes that will lead to a later release, and its first commit should be to add a dev-suffix (.9000) to the current version number (don’t increment <major>.<minor>.<patch>).
    • Especially when cooperating, it is counteradvised to push directly to this branch; better do so through pull requests from feature branches.
  • Eventually, the development branch’s last commit before merging to main will be to increment at least one of <major>, <minor> or <patch> and to drop the dev-suffix from the version number (i.e. in the DESCRIPTION file). Such final commits should happen directly on the development branch. No later than that commmit (but it can safely be done earlier), also the .zenodo.json metadata file must be updated to the new release version number.

Steps and tricks in git

The preceding philosophy leads to following steps and guidelines:

  1. Make commits (in your local clone of the remote repo on Github) in your own git branch, branched off from the base branch you wish to contribute to – below referred as <base> branch. Let’s call your new branch the <feature> branch.
    • In general, the base branch will be a dev* branch, or it could be a feature branch of someone else you wish to make a contribution to.
    You can push your branch to the remote as often as you like, as it will not influence other branches (first time: do git push -u origin yourbranchname; afterwards git push suffices). It serves as a backup and enables others to work with you on that branch.
  2. Meanwhile, make sure that your branch stays up to date with evolutions in the base branch. This is needed to ensure a smooth merge of your branch to the base branch later on.
    • To do that in your local repo, you can run git pull origin <base> while having your feature branch checked out.
    • If you also wish to update your local base branch in this process, you can first git checkout <base> followed by git pull, then switch back to git checkout <feature> and merge the base branch with git merge --no-ff <base>.
    If any merge conflicts arise at this stage, resolve them in your own branch.
  3. Propose to merge your commits into the base branch: after pushing your branch to GitHub (which you can do repeatedly), this starts with making a pull request (PR; actually this is a merge request) and assign at least one reviewer before a merge can be decided. At that moment, open online discussion in the repo is possible on your changes (for other open discussion that you want to start, make an issue). As long as no merge is performed, more commits can be added to this PR with git push, e.g. to implement requested changes by others.
    • make sure to correctly set the base branch in the pull request (because the default is main).
  4. After your PR is merged, pull the base branch and clean up your local repo in order to keep up with the remote.

Git resources