NIVANorge.github.io

NIVA Norge on GitHub

Welcome to NIVANorges GitHub page!

This page contains general information on how NIVA’s source code on GitHub is organized and documented. This page also document how new Git repositories should be organized (i.e. a “best practice” for source code on Git).

For more information about NIVA and NIVA’s services see https://www.niva.no/en.

For a quick introduction to version control with Git and GitHub see:

• https://guides.github.com/activities/hello-world/

GitHub also provides a graphical user interface for version control and integration with GitHub:

• https://desktop.github.com/
• https://help.github.com/desktop/

Project organization

The root folder of the project should (always) include a README.md file describing the content and purpose of the repository.

The root folder will (typically) also contain information and configuration files for building (Docker images) of the project, dependencies, etc. The amount of such information and configurations will depend on project type and size.

Smaller projects can have all it’s source code in the root folder, but as the project grows consider moving code into folders and subfolders.

Project documentation

All project documentation should go into the source tree, this ensure that “everything” is in the same place, and that the documentations follows and is developed alongside the source code.

NIVA projects have three levels of documentation:

• README.md

As mentioned above, all projects should have a readme file in markdown format with a basic overview of the project.

• doc/ folder

Optionally, additional written documentation, figures, etc. should go into a separate folder named doc. This folder can contain all kinds of documentation, but the preferred format is markdown.

• Source code comments

Source code should be written in accordance with appropriate coding standards for the language in question. And the code should contain appropriate comments, doc-strings, etc.

Markdown

Markdown is a simple and lightweight text formatting language. Markdown is plain human readable text, and it can be rendered by many tools, including web publishing frameworks. Basic Markdown is very simple and the following web pages will make you productive in Markdown in less than 10 minutes :-)

• https://guides.github.com/features/mastering-markdown/
• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Branching

Our branching strategy is simple. Any ‘mature’ project will have at least two branches

1. main
2. dev

Where master is the stable production branch, and the dev branch is ready for and/or deployed on our test system. New features and bugfixes are done in separate bugfix or feature-branches. When these changes are done, they are merged into dev and master. For projects with more than one (main) contributor these merges are done through pull requests.

Note that for many projects we have implemented automatic deployments on push to master and dev branch. This means that untested code should not be pushed to these branches, and ‘untested’ code should never be pushed to master, NEVER!!!

For more an introduction to branching Git see:

• https://www.atlassian.com/git/tutorials/using-branches
• https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

Issues

For tracking and managing, bugs, bugfixes, feature requests, discussion, and code collaboration; we use GitHub Issues feature (instead of e-mails).

The purpose of and how to use issues is well documented on GitHub.

• https://guides.github.com/features/issues/
• https://help.github.com/articles/about-issues/