nbisweden / development-guidelines Goto Github PK

Find and correct the "yearly columns" of animals that were sold outside of the system and later returned.

Update the section on code comments with requiring "what the code does" in the comments, as well as examples/links to best practices.

Relevant for e.g. python projects. Enables reproducibility.

Here are the links to semantic versioning and semantic commits.

Add section on tips on how to do packaging with for example

• Containers
• Conda
• Github releases
• and so on

If code needs compiling, ensure that all commits compile and produce a working binary. Otherwise git bisect might have problems finding the actual commit that breaks functionality.

Introduce Draft pull requests
An author might want early feedback about some complex code base that might need extra tuning. The code might be still in early stage, but the comments can be valuable for the author.

Introduce PR templates
Beneficial if multiple persons are involved writing the code, see example below

Describe the pull request:

• Bug fix
• Functional change
• New feature
• Code cleanup
• Build system change
• Documentation change
• Language translation

Pull request long description:

Changes made:

Related issues:

Additional information:

Release note:

Documentation change:

Mentions:

Should have a CONTRIBUTION file to help indicate that outsiders are welcome to contribute in our open source projects!

Team 🟨:

We usually use docker for easy setup for deployment and reproducibility across team members. Some recommendations about this could be in the document or in a separate document.

Another alternative to docker that's used in uppmax (afaik) is Singularity.

Dan philosophises: Although mostly removes the "works on my computer"-problem, where code that consistently works on your computer fails when your colleague tries it, it comes with some problems on its own. Setting up docker for your project can be surprisingly time-consuming. One reason for this is that when trying you typically need to rebuild everything. Volumes (and possibly other caches?) not being reset and emptied can be another problem. Another can be images and non-containerized repositories not being in sync.

This also happens when you check out another branch and need to rebuild everything to try it out.

I am all ears if you know some better way to use docker or have some alternative.

If code is to be referenced in an online article or publication, authors might consider using Zenodo or minimally, tagging the codebase accordingly, so that reproducibility is achieved.

Suggestion from team Yellow:
The Hitchhiker's guide to NBIS could be kept here, instead of in google docs. This would make it easier to find and maintain.

Should we have a section on reproducibility? This would include guidelines for how to use versioning, package versions, etc. - particularly for analysis tools.

Add link to other NBIS document

With regards to comments that I left on issue #14, if Go is added as a language that we may provide expertise in, then the following link could be used for best practices: https://talks.golang.org/2013/bestpractices.slide#1

(Thanks to Kostas for the link)

Suggestion from team Yellow:
Write a section on how to work with GitHub issues.

Similar to the existing guidelies for worknig with PRs.

• Should each new feature start with an issue?
• When are issues closed, and by whom?
• Recommended things to include / exclude
• ...

Suggestion from team Yellow:

Add information and links on this topic. Do we have a standard/preferred way of working?

add
Everything that includes sensitive data should be in .gitignore

Possible make links to:

• Docker containers should use secrets for ssh keys and sensitive data
• Kubernetes

If a commit description contains and it should most probably be split into two commits.

Some codebases might require of a special considerations section, where security assumptions and specific configuration decisions are outlined

Should have links to guides for generating documentation for our most common languages (combined with our thoughts on commenting):
Pydoc, JSDoc...

Related to #19

Use sane defaults for variables and ENVs. Using defaults for local testing is a bad idea.

A sentence in README.md can be improved to make it more clear.

Suggestion from team Yellow:

The list of "top languages" now includes

• Python
• Shell
• Perl

We suggest that this is updated to reflect the knowledge, use and preferences within the dev group, instead of NBIS in general. Top language would be Python & Shell, and recommended once include TypeScript, Perl, C/C++, R etc.

Someone should merge the develop branch into the main branch.

I noticed there were a PR against the main branch, which was already handled by old (merged) PRs on the develop branch. In general, development should happen on the develop branch.

If the document is in a "stable enough" state, it may be a good idea to merge the develop branch into the main branch.

I'm writing this as an issue rather than just going ahead and merging the branches as I don't know whether there is currently ongoing work to modify the document.

• Use continuous integration (CI) for repositories of tools, pipelines or web-servers etc.
• What should be the recommended CIs
• Instructions about how to use CIs (or just links to instructions)

I usually try to keep a changelog in my own development projects, because I think it gives a good overview of what has happened. Maybe you want to add some text about that. I personally like the recommendations given at https://keepachangelog.com.

This issue is somewhat related to issue #41 on semantic versioning.

In sections with coding format and code reviewing, it will be great to link to some examples from the NBIS github repository (or somewhere else).

• some screenshots might also be nice to be added.

Suggestion from team Yellow:

We appreciate that there is a standard licence to use for all (most) projects, but would like to see a discussion/motivation on which license to go for (GPLv3 vs eg MIT).

Include that you should write test at the same time as you write the code

Add mentioning of how to work together on a single branch:

• Only do this after agreement.
• Otherwise, work on a separate branch and merge later.

The main thing is to communicate.