Informedica Software Development

Software development for Informedica has been a one man show. Maybe that’s about to change. However, this means that the development process has to change as well. In this blog I propose a development process to enable this change. The fork and pull model will be used to cooperate.

General Principles

I try the following general principles (which I failed to follow in the past, much to my regret!):

1. Do the simplest thing possible (KISS)
2. Less is more
3. For libraries, all code should run in the FSI

Git

For code repository management git is used. To download git and read everything about git got to: https://git-scm.com/. When using git the first time use the

# initializes new repository
git init
# add all new code files to the repository
git add -A
# commit to the repository
git commit -am "chore: initial commit"

The commits you make should be documented using the following tags:

• release: obviously to release, mention the version number
• feat: new feature
• fix: fix a bug or problem
• docs: document
• refactor: refactoring
• perf: improve performance
• test: add test
• chore: do a chore (build, libs, etc..)

Note! There should be a .gitignore file in the root folder that should look like:

# Ignore all files using an opt-in approach
*

# Add .gitignore and .gitattributes
!.gitignore
!.gitattributes

# Add license
!LICENSE.txt

# Add todo list
!ToDo.txt

# Add md files
!*.md

# Add fsx files
!*.fsx

# Add build files
!build.sh
!build.cmd

# Add build props
!Directory.Build.props

# Add global json
!global.json

# Add editor config
!.editorconfig

# Add vscode config
!/.vscode/
!/.vscode/*.json

# Add proc file
!Procfile

# Add local tools config
!/.config/
!/.config/*.json

# Add paket targets
!/.paket/
!/.paket/Paket.Restore.targets

# Add github folder
!/.github
!/.github/*
!/.github/ISSUE_TEMPLATE/
!/.github/ISSUE_TEMPLATE/*
!/.github/workflows/
!/.github/workflows/*

# Add source files
!/src/etc...

So an “opt-in” approach will be used. That means you have to be explicit what you add to the repository instead of the normal approach where you do not specify what to add, but what to ignore. The problem with the latter approach is that, first, you can accidentally add sensitive material to your repository (very difficult to remove), and, secondly, it keeps your repository much cleaner.

You can check what files will be added by running:

git status

In VS code and VS studio you can also look at the coloring of your files in the explorer

GitHub

Ofcourse all libraries and applications are hosted on GitHub. To learn the basics of using GitHub you can go to: https://lab.github.com/.

I have a personal account and a project account for Informedica. The idea is that you will fork a project repositories to your personal account, to start collaborating, and then will add an upstream remote for development in that repository. For example when you want to develop the Informedica.Utils.Lib you should do the following:

1. Fork (if not already done) the repository to your personal account
2. Clone the repository to your local PC/Mac
3. Add a remote branche

git remote add upstream https://github.com/informedica/Informedica.Utils.Lib

To check whether you correctly entered the url, you can use the following command.

git remote -v

You then can develop in your downstream origin repository and make a pull request to the upstream repository to apply my changes. It is important to note that to make the upstream merge seamless it is of help to rebase your origin before making the pull request. Rebase will make sure that your downstream repository is up to date with the latest upstream repository and will show all commits in a linear fashion.

Build Pipeline

I previously used ProjectScaffold and MiniScaffold to structure my projects. Unfortunately, ProjectScaffold is not actively maintained and MiniScaffold is really good but still under development and difficult to apply to existing projects. Also, lately with the new dotnet CLI, it has become much easier to perform build, test and other maintenance tasks.

For know I want to use the following build pipeline:

1. For the build tools use the dotnet-tools.json in the .config folder
2. For dependency management use Paket

The dotnet-tools.json looks like:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "paket": {
      "version": "6.1.3"",
      "commands": [
        "paket"
      ]
    }
  }
}

Paket

Paket is used to manage dependencies. The simplest way to get up and running with paket is to install it as a local CLI tool.

# generate a new tool manifest i.e. .config/dotnet-tools.json
dotnet new tool-manifest
# add the paket cli tool to the manifest
dotnet tool install paket
# restore the all tools (i.e. paket) locally
dotnet tool restore
# initialize paket (when using first time)
# creates a paket.dependencies in the root
dotnet paket init
# add a dependency to a project
# this will create and add the paket.references to the project folder
# will also create a .paket/Paket.Restore.targets file
dotnet paket add MathNet.Numerics.FSharp -p <path>