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.
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.
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.
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.
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:
See below if you want to contribute code for your idea as well.
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:
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. 🌟
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!
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
_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.
Functions are described as comments near their code and translated to documentation using
roxygen2. If you want to improve a function description:
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.
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
When writing functions for
rasterpackages for data reading. Discover the human-friendly way of coding a data processing pipeline through the use of pipes! Organise data in R in a tidy way in order to avoid troubles later on. Recommended resources to get started are:
dplyr::as_tibble()to return it as a tibble instead. A tibble is a dataframe that makes working in the tidyverse a little easier.
We try to follow the GitHub flow for development.
git pull upstream master.
R CMD checkusing
devtools::check()and aim for 0 errors and warnings.
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:
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
master(branch tip) must always have a
<major>.<minor>.<patch>version number in the
DESCRIPTIONfile. It is the latest released package version.
masterwhich do not change the package code itself, but only website setup and repo documentation, must inherit the same release version number.
<major>.<minor>.<patch>.9000. It follows that they never appear at the tip of the
masterbranch. Non-package commits may follow this route as well: it is safe for all new commits.
mastercan have various names. However, there is always at least one development branch whose name begins with
dev. For example:
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
masterwill be to increment at least one of
<patch>and to drop the dev-suffix from the version number (i.e. in the
DESCRIPTIONfile). 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.jsonmetadata file must be updated to the new release version number.
Steps and tricks in git
The preceding philosophy leads to following steps and guidelines:
<base>branch. Let’s call your new branch the
dev*branch, or it could be a feature branch of someone else you wish to make a contribution to.
git push -u origin yourbranchname; afterwards
git pushsuffices). It serves as a backup and enables others to work with you on that branch.
git pull origin <base>while having your feature branch checked out.
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>.
git push, e.g. to implement requested changes by others.