README guidelines¶

Introduction¶

These guidelines apply to the content of the README files in Git repositories created at Digital infrastructure. We offer a template here that you can use as a starting point, the document you are reading now is the accompanying documentation.

Motivation¶

We need to document our software because it is too complex for others to understand without it. We need to make sure that our software products can be used and can be maintained. README files are usually the first documentation page encountered by users of our repositories. We created a template to address the issue of lack of consistency and lack of completeness in our README files, making sure we all include the necessary information.

How to use the template?¶

Copy this README template into your git repository as README.md, edit it and commit and push it. Make sure you're copying the actual markdown version (e.g. from git) and not any rendered version.
Observe the instructions in these guidelines. Elements marked with MUST are considered mandatory, some are even used in the automatic pipeline that displays the tool metadata on external services (e.g., INEO, SSHOC marketplace, etc.). The elements without "MUST" are optional, but it is still recommended to add them.

README sections¶

Badges¶

It is strongly recommended to start your README with so-called badges. Badges are little images that display on a single line on top of the README and express, at a quick glance, some of the necessary metadata. They are often easily machine-interpretable and are also used by our metadata harvester.

These are some recommended badges:

Repository status - A README MUST make clear what the current maintenance status of the project is. See https://repostatus.org for the recommended vocabulary and markdown snippets to copy into your README. Here they are as well:
- - Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.
- - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
- - Initial development has started, but there has not yet been a stable, usable release; work has been stopped for the time being but the author(s) intend on resuming work.
- - Initial development has started, but there has not yet been a stable, usable release; the project has been abandoned and the author(s) do not intend on continuing development.
- - The project has reached a stable, usable state and is being actively developed.
- - The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.
- - The project has reached a stable, usable state but the author(s) have ceased all work on it. A new maintainer may be desired.
- - The project has been moved to a new location, and the version at that location should be considered authoritative.
DOI badge - If you have a DOI for your software at a more persistent repository, you SHOULD publish it in a badge if possible:
- Zenodo, example: .
CI Tests - A badge SHOULD show the latest status of the continuous integration tests of your software. Shows green or red depending on success.
- Github, example:
CD Result - Status of the latest automatic deployment (if applicable). Shows green or red depending on success.
- Similar to CI
Latest release - Badge pointing to the latest release
- on Github, example:
- on the Python Package Index, example:
- on Crates.io (Rust), example:
Documentation - Link to a documentation (often autogenarated/deployed API references). Badge colour reflects deployment success.
- on Readthedocs.io, example:
- on Docs.rs (Rust), example:
Software Heritage Archive badge - See https://www.softwareheritage.org/save-reference-research-software/. Example:

Software name¶

The software MUST have a name. This is the name for presentation purposes and must be human readable. Put it as the main title heading (h1) just below the badges.

try to use the same name, or a short form thereof, as the name/identifier for your repository
Optionally add a colon with a subtitle (or something like an acronym expansion or even minor description).

Description¶

A README MUST have a short description somewhere near the top, preferably just below the title header. It briefly explains at a glance what the software does (what problem it solves) and for whom it is intended.

On platforms like Github or Gitlab, you SHOULD put the same short description in the repository's metadata.

Logo¶

You MAY add a project logo to make your project more appealing. Even though the source is technically markdown, users often resort to an HTML snippet to add and center a logo. See for example: https://github.com/knaw-huc/suriano .

Table of contents¶

If your README file is too long or contains several sections, you SHOULD consider adding a table of contents with links to the subsections. Always make sure to use relative paths only so it is not tied to a platform like Github.

To create a table of contents automatically for your README file: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#auto-generated-table-of-contents-for-readme-files

Introduction¶

A README MUST have an introduction section that contains a larger description of your project:

Use a header to name this section, either "Introduction" or "About"
The introduction is meant to indicate what the repository does and is about, also to set up the context of the repository. Try to answer these questions in the description, some content may be repeated later, but here you name the most important aspects:
- What is it?
- What does this software/project do? What problems does it solve?
- Context: is it part of a general project? If so, mention the project and include a link to the project page:
  - general project website (e.g., Lenticular Lens project page) and/or funding agency (e.g., CLARIAH)
  - other documentation and/or other related repositories (sometimes more than one repository is part of one project, make sure users can navigate across the related repositories)
- For whom? What is the audience for the software/project?
  - is it for internal use?
  - is it for end-users (e.g., researchers community, curators, etc.?)
- What does this repository contain?
  - Make sure you also describe what do you find in the repository and how you can use it (e.g., if you have a folder called docs, explain that it contains diagrams or extra documentation files).
  - In large repositories with a lot of hierarchy (subprojects etc), you can include READMEs at multiple levels to avoid clutter in the primary one.
- Features
  - List the main features/functionality of this code
  - This can be as part of the description section, or as a separate section if features need to be explained in detail.
- Technical architecture
  - Describe the core components of the software: db, server, backend, api, cli/ui (different from list of dependencies, this is more about each building block of the software and what is its purpose in the code)

Feel free to split the introduction into multiple sections if it gets too long/too detailed.

Installation¶

A README MUST have instructions on how to obtain, build and install the software.

How does the user obtain your project? (e.g. git clone)
- If your software is packaged for certain platforms/distributions/language ecosystems, mention it:
  - Python Package Index example: pip install my-software
  - NPM/js example: npm install my-software
  - Debian/Ubuntu Linux example: apt-get install my-software
  - Alpine Linux example: apk add my-software
  - Homebrew example: homebrew install my-software
The README SHOULD make explicit any software and minimal hardware requirements the software relies on. This includes making explicit the software's main dependencies, target OS, and minimally required resources.
Provide build instructions for software that is to be compiled from source code. (e.g. ./configure && make && sudo make install)
If an OCI (e.g. Docker) container is available, mention it and provide build instructions for the container.

Make sure the installation instructions are kept up to date with any changes in the system. Also provide instructions on how to update to a new version of the software if the procedure significantly differs from fresh installation or if database/configuration migrations are involved.

Usage¶

The README MUST provide (or link to) usage instructions for a quick start, explaining how to start the system and how the first task can be performed with the system.

If it is a command-line application, provide examples of command-line invocation.
If it is a programming library, provide instruction how people can add it to their project and example code on how to the most common functions.
If it is a web-service, give examples of how to call the most common endpoints.
If you offer a Graphical User Interface (e.g a web-based user interface), explain how to use it.
If you use containers (e.g. docker or docker compose), provide an example of the docker run or docker compose up commands.

Make sure the usage instructions are kept up to date with any changes in the system!

You can cover a few of the most common use-cases, also mention if there are examples elsehwere of use of this software/code.

Documentation¶

For larger projects, the installation and usage sections in a README are not sufficient and would quickly become unwieldy if all details were squished in there. Projects SHOULD have further documentation aside from the README, and the README MUST link to it. The exact nature of the documentation depends on the type of software and the intended audience.

Examples of such documentation:

Tutorials
- Possibly interactive (e.g. jupyter notebooks, marimo notebooks, R notebooks)
API References (aimed at technical users/developers)
- For Web APIs, we strongly adhering to the OpenAPI Specification
- Automatically extract API references from your source code using appropriate software fitting your language ecosystemen (e.g. doxygen, sphinx, rustdoc, javadoc)
Technical specifications (of data models, system architecture etc)
Installation guides (how to install the software, aimed at system administrators)
Administration guides (how to configure the software, aimed at software administrators)
User guides (aimed at end-users. How to use the interface?)
- For command-line interfaces and technical users, these can also be in the form of classical man pages.
Deployment guides and instance-specific documentation (for service maintainers/devops), may be specific to an infrastructure: where are the backups, how to do certain interventions like: restore data, migrate, scale up, scale down, undeploy; also a report of interventions that have been done during the lifetime of the app/service.
Presentations, technical papers, posters, screencasts, demo videos, demo instances. These can often also go in the references section at the end of the README.

Support and Roadmap¶

The README MUST refer users to a public support channel (e.g. an issue tracker, mailing list) where people can submit bug reports and feature requests.

The README SHOULD also make clear what functionality is still awaiting implementation, refering to an issue tracker with milestones may suffice already.

The README SHOULD also make clear who is/are the current maintainer(s) of the software. This section might be a good place for that.

Licence¶

The software should have an appropriate open-source software licence. The full licence text itself MUST be kept separately as plain text or markdown in a LICENSE.md file (or LICENSE or LICENCE or COPYING). Automatic metadata harvesters can use this information.

The README SHOULD briefly mention the license. Example: Licensed under the GNU General Public Licence v3

Check the OSI-approved licences and choose on of the popular licences mentioned there or EUPL-1.2. Be aware of the difference between copyleft (e.g. GPL) and permissive licences (e.g. MIT) and make sure your licence doesn't violate that of the dependencies you build on.

Authorship MAY also be made explicit in this section if you want.

Changelog¶

You SHOULD keep a changelog in the git repository (named CHANGELOG.md or NEWS or RELEASES) that lists all releases along with the release notes for each release. Release notes are important for users to give them a broad overview of changes, perhaps with headings like fixes, breaking changes, etc...

A changelog typically gives a higher-level overview than the raw git log.

Also see https://keepachangelog.com/ for best practises.

If you don't keep a changelog in git but use the release functionality of a platform like github or gitlab, then you can alternatively point to that in this section.

Contributing¶

A README SHOULD provide (or link to) instructions on how users can contribute to a project. Open source projects should be open to contributions. The actual instructions are often provided in a separate CONTIBUTE.md file.

Contribution guidelines may for example explain the preferred coding style, the ways to do push/merge requests or send in patches, the review procedure, how to formulate commit messages, or provide additional technical :information on understanding the codebase.

See also https://contributing.md/how-to-build-contributing-md/ for guides and best practises on this.

Frequently Asked Questions¶

A list of frequently asked questions MAY be added to the README. For example to help troubleshooting or to make clear the scope of a project.

References¶

A README MUST provide references to any supporting literature used in the readme, e.g., if you cited a publication, add the full reference here. This is also a good place for project publications where the software is explained/mentioned

Acknowledgements¶

A README MUST acknowledge the funders or any other person or institution who has collaborated.

Companion files¶

Whilst a README is the first document any user of your software should study, not everything should be crammed in there, especially not if a project grows large. In the Documentation section we already gave examples of accompanying documentation.

Common companion files you can use are:

codemeta.json - a JSON-LD file with full metadata using the codemeta vocabulary. See CLARIAH Software Metadata Requirements on how to provide that.
codemeta-harvest.json - a JSON-LD file with metadata using the codemeta vocabulary. See CLARIAH Software Metadata Requirements on how to provide that. This file only contains a subset of manually provided metadata that will be added alongside anything that can be automatically harvested.
AUTHORS - a simple plain text file that lists the authors of the software, one author per line: Full name <mail@provider.com>. These should be people rather than institutions.
MAINTAINERS - a simple plain text file that lists the maintainer(s) of the software, one maintainer per line: Full name <mail@provider.com>. These should be people rather than institutions.
LICENSE.md or LICENCE.md or LICENCE or LICENSE or COPYING - The full text of the software license
CHANGELOG.md or HISTORY or NEWS or RELEASES - The changelog describing notable changes between releases of the software.
CONTRIBUTING.md or CONTRIBUTING - Contribution guidelines.
CITATION.cff - A plain text file with human- and machine-readable citation information for software (and datasets). Code developers can include them in their repositories to let others know how to correctly cite their software. See https://citation-file-format.github.io/