Skip to main content

Open Sourcing Repositories

Open-source your repository in 5 easy steps.

info

The repository templates here adhere to the explained steps and its encourage to use them.

Minimum Requirements​

1. Repository Name​

Use consistent naming:

  • kebab-case by default
  • follows existing naming convention (e.g. <software>-api, <software>-cli)

2. Description​

  • Add a GitHub/GitLab "about" repository description in one sentence.

3. README​

note

Larger projects may need additional documentation

Summary Guidelines
  • What is this tool about (1-2 sentences)
  • Which problems does it solve?
    • A few sentences, depending on the breath of the solutions.
    • Possibly a few links to explanations of the problem.
  • Avoid acronyms without explaining them.
Installation Guidelines

Explain how to set it up from "zero"

  • Expect users to have a computer and OS, nothing more.

  • Provide a self-containing, easy and deterministic install instruction instead of a lengthy explanation how to install each dependency manually, e.g:

    Explain how to enable the development environment either by a

  • Explain all other non-automated necessary install steps by linking to guidelines.

  • If possible list all dependencies and requirements as well.

Usage Guidelines
  • Make sure that a minimal example is reproducible directly after installation:
    • Demonstrates that installation was successful.
    • Add sample data to the repository if needed or include a downloader script.
  • Examples should reflect typical use cases.

4. Reusability​

A LICENSE.md file, selected from a set of well-known options (see Choose an Open Source License and Software Licenses in Plain English).

5. Findability​

Add relevant topics (GitHub or GitLab). Try to reuse existing topics like ontology, workflow, cli, rest-api, library etc. See the list on GitHub, list on GitLab).

Next Steps​

For larger projects, the recommendations above can be extended to further increase accessibility.

Project-Specific Recommendations​

API​

  • Include an API reference in your documentation.

Projects Tied to a Publication​

  • Use Zenodo to assign a citable DOI to your repository.
  • For GitHub repositories, use the Zenodo-GitHub integration to automatically update the Zenodo record on each GitHub release.
  • Complete the CITATION.cff file (see repository template) in the root of the repository.
  • Consider publishing your dataset in a visible community. For example, the EPFL Community.

Documentation​

  • Documentation of larger projects should aim for Diátaxis (not only a README), including:
    • Tutorials
    • How-to Guides
    • Technical Reference
    • Explanations