This document briefly describes the version tags, release model, update notice, version checkout, and branches used with the FS git repo. It also outlines the steps in initial and update installs of the FS, including from an archive, and sending changes to the maintainers.

1. Version tags

An example version tag is:

10.1.0-beta1

The general form of FS version tags is:

MAJOR.MINOR.PATCH-STRING

Where:

  • MAJOR, a number, indicates a major release, e.g., 10. Note that MAJOR does not start with a v.

  • MINOR, a number, indicates a minor release, e.g., 1.

  • PATCH, a number, indicate the patch number, e.g., 0. Non-zero patch numbers are only used for fixes to MAJOR.MINOR releases (before version 10.0.0, non-zero PATCHs were used in regular releases).

  • STRING, a string, which is optional and when non-blank provides additional information, e.g., beta1. If STRING is empty, the dash - is omitted.

If the version tag has changed since the last time the FS was made, the version tag is inserted in the FS (and drudg) code and compiled in. If the version that is made does not correspond to a tagged commit, additional information is automatically appended to identify the specific commit, e.g.:

10.0.0-beta1-58-g229f696e

The general form of what is appended is:

-n-gSHA-dirty

where:

  • n is the number of commits that have been been made since the last commit tagged with a version string, e.g., 58.

  • SHA is the (unique) SHA prefix of this commit, e.g., 229f696e.

  • -dirty is appended if the working directory contains changes that have not been committed. When -dirty appears, the ability to identify what version was run is lost. This should be avoided.

This format is only present for versions 10.0.0-alpha2 and later.

2. Release model

When an FS release is made, a particular commit is tagged with the version. A lightweight tag is sufficient, but an annotated tag can be used. Official releases never have a non-blank STRING. However, alpha and beta releases will have appropriate STRING values, e.g. alpha1, beta2, etc. Other values may be used as needed.

There is a basic distinction between MAJOR.MINOR.0, i.e., with zero PATCH, a feature release, and non-zero PATCH, a patch release. Generally feature releases include significant feature changes, but also occur when a patch is not just a “quick” install for the users. A patch that requires significant changes, including, but not limited to reboots due to changes in shared memory size, should be promoted to being a feature release. The goal is that patch releases should be safe for operational stations to install without needing a significant amount of time, testing, or otherwise being a risk to operations.

3. Update notices

For each release, there should be an update notice in a file with the its name in the form:

/usr2/fs/docs/releases/<MAJOR>/<MINOR>/<name>.adoc

The update notices should have a complete description of the changes and installation instructions relative to the previous feature release, for example 10.2-beta1 relative to 10.1 and 10.2.1 (and possibly 10.2.1-beta1) relative to 10.2. The values of <name> are fully discussed in the following two subsections.

All these files should be visible on the gh-pages in HTML format.

3.1. Feature releases

For feature release notices (including associated releases with a non-empty STRING), <name>.adoc omits the .0 patch level part of the release tag, e.g., 10.2.adoc (and 10.2-beta1.adoc). This makes it possible for the feature release (with an empty STRING) notice file names, and links to them, to be re-used for an update to a feature release including the latest patches. It is not necessary to rename them or generate almost completely redundant versions for the patches. The contents of the feature release notice should be updated for the patches, i.e., the latest patch tag would be used and any installation and documentation changes would be included. Thus users who update to a feature release after patches have been released would use the original link to install to the latest patch. The notice for applying a patch to a feature release is covered in the next subsection.

In the gh-pages, it may be expedient to provide a symbolic link for a feature release that points to the latest pre-release (for example, 10.2.html → 10.2-beta1.html) until the feature release is finalized. This will allow links in issues, discussions, emails, etc. that are created before the final release to still point to the latest information after the release. What is appropriate will need to be decided on a case-by-case basis.

In the documents, references to feature releases, omit the patch level, e.g., 10.2 (and 10.2-beta1).

Note
 The feature release tag must still include the .0 patch level, e.g., 10.2.0 (and 10.2.0-beta1).

3.2. Patch releases

All patch release notices use the full tag for <name>.adoc, e.g., 10.2.1.adoc (and possibly 10.2.1-beta1.adoc).

In the documents, references to patch releases use the full tag, e.g., 10.2.1 (and 10.2.1-beta1).

3.3. Latest commit

A <name>_to_latest.adoc file covers changes on that release’s branch since the most recent feature (and possibly patch) release, e.g., 10.2_to_latest.adoc (and 10.2.1_to_latest.adoc). It begins basically empty after a release. It accumulates the installation steps and changes until the next release. At a new release, it is converted to a new <name>.adoc file for the new <name>.

Note
 Those using the latest commit are understood to be experts and are expected to manage differences in the update steps when updating to the next release themselves. Advice may be available of course, but documentation is not provided.

4. Branches

The default branch in the repo is main. This is the branch that is checked out after a clone operation from github. The main branch represents the primary line of development and should include most of the feature releases.

In order to patch an existing feature release, a maintenance branch is normally used. For example, to create a maintenance branch 10.2 for feature release 10.2.0:

git checkout -b 10.2 10.2.0

The changes created on any maintenance release should be rebased onto main as soon as they are stable. Maintenance branches should be retained long term both for possible future extension and to preserve the history.

To develop a new feature, a feature branch can be created at any point. Likewise, for bug fix branches. Once they are considered to be stabilized enough they are merged into the appropriate branch, main or a maintenance branch, and then deleted.

Patch releases are normally made on maintenance branches. However, if a patch is needed and there have been no changes on main since the corresponding feature release, the patch can be released on the main (probably having been developed on a bug fix branch first). Otherwise, a maintenance branch should be made.

Despite feature releases normally being on the main branch, one may occur on a maintenance branch for a patch that has been promoted to a feature release. In this case, a maintenance branch for a new feature release is created at the tip of the existing maintenance branch. For example, to make a 10.3 maintenance branch off the 10.2 maintenance branch:

git checkout -b 10.3 10.2

and the new feature release is placed on the new branch. Likewise, a maintenance branch can be created from a patch release on main:

git checkout -b 10.2 10.2.1

5. Version checkout

It is always possible to get a specific release version by checking out the tag for its version string:

git checkout tag

Commits that do not have a version tag are not considered releases. Users can check them out, but they may have bugs and/or incompatibilities with local files and station software of the previous tagged version.

The last commit on a branch, the tip, is checked out with:

git checkout branch

It is not necessary that untagged commits on main or a maintenance branch be in a state that is releasable. However, it is helpful to developers, and to a lessor extent for users, for the branch tips be in a usable state. This is largely achieved by not merging or rebasing feature branches into the branch that aren’t in a fairly complete state. It is acceptable to make new commits significantly changing the impact of previous commits, if they still result in a usable tip.

6. Making a release

Before a release is made, the update notes should be prepared. For feature releases, the instructions should include all steps to upgrade from the previous feature release. If there were significant changes in patch releases for that version, they can be included by reference to the last patch release instructions at the time of the new feature release. A description of the changes should be included as well.

For patch releases, the installation instructions can be abbreviated to cover just what is necessary to upgrade from the corresponding feature release plus instructions for all previous patches for that feature release. Covering all the previous patch releases, should not be hard, since previous patch notes can be included explicitly or by reference. A description of what has been fixed should be included.

To make a release:

  1. Finalize release, including update notes, committing all changes.

    Final commit message: Finalize tag

  2. git push

  3. git tag tag

  4. git push --tags

  5. Change to the docs/ sub-directory

  6. Generate and push the .html files to the gh-pages branch on github.

    Directions are in making_gh-pages.txt.

  7. On the github page for the repo, select release

  8. Select Draft a new release

  9. Enter version string as an existing tag and select branch

  10. Enter a release message as the Description

  11. Leave Title blank

    Do not include pre-release or the version tag in Title since they are automatically prepended to the announcement email.

  12. If not for production, select This is a pre-release

  13. Select Publish Release

7. Installation

To find the most recent release for installation, go to:

https://github.com/nvi-inc/fs/releases

Typically, you should use the most recent patch release for the most recent feature release. If there have not been any patch releases for that feature release, use that feature release itself, i.e., with the version string ending in zero. Versions with a trailing -string are not intended for production. Use the tag of the release you have chosen for tag in the instructions below.

7.1. First time FS installation

As root, execute:

  1. cd /usr2

  2. git clone https://github.com/nvi-inc/fs fs-git

  3. cd fs-git

  4. git checkout -q tag

    Use the version tag of the release you are installing.

  5. make install

    Answer y to confirm installation

  6. Log-out as root and log-in as prog

  7. make >&/dev/null

  8. make -s

    If there is no output from the above command, then the make was successful.

  9. Reboot

You can then login as oper and run the FS, but you will need to customize the control files in /usr2/control before you can do anything useful. Additionally, you may need to add station software, particularly antcn if you want to control an antenna

7.2. Installing FS updates

As prog:

  1. cd /usr2/fs-git

  2. git fetch

  3. git checkout -q tag

    Use the version tag of the release you are installing.

  4. make >&/dev/null

  5. make -s

    If there is no output from the above command, then the make was successful.

  6. Reboot

    A patch update may not require a reboot, please check the instructions.

Additionally, you will need to follow the update instructions. There is usually a link to them in the release announcement, which can be found at https://nvi-inc.github.io/fs/releases/.

7.3. Installing from an archive

The primary method of distributing the FS is with the git repo from github. This makes updates, particularly patches, much easier to install. However, if it is not possible to use git, you can get a .tar.gz archive from the release page.

To install from the archive (use the tag of the release you are installing):

  1. Log in as root

  2. cd /tmp

  3. wget https://github.com/nvi-inc/fs/archive/tag.tar.gz

    Tip
    		 If you don’t have wget or if there another problem with it, such as its TLS version is too old (this is the case for FSL8), you can retrieve the archive on a different local machine and move it to /tmp on the FS machine.

  4. cd /usr2

  5. tar xzf /tmp/tag.tar.gz

    Tip
    		 The directory name created when the archive is un-tar-ed will include the tag of the release, e.g., /usr2/fs-10.0.0. There is some advantage to not modifying the name of the directory or its contents. The tag from the directory will be recorded in the FS release log entry and displayed by the fsversion command. If you want to change the contents of the directory, it is recommended that you make a copy with a new name, e.g., /usr2/fs-10.0.0-mychange, and modify the new directory. The portion after a second dash, “-”, (in this example, mychange) can be an arbitrary string (without spaces and forward slashes, “/”) up to 32 characters. Using appropriate names will help track what, possibly changed, version you are using and make it easier to return to previous versions. The /usr2/fs link will need to be changed to point to the different version you want to switch to and the machine rebooted (assuming you have already run make in the directory).

  6. cd /usr2/fs-tag

  7. At this point you have two options:

    1. Set /usr2/fs link, file ownerships, and file permissions

      If this is a first time installation of the FS or it is an update that you want to use immediately, then execute:

      make install

      Answer y to confirm installation

    2. Set only the ownerships and permissions

      If you only want to build this version and not make it operational yet, then execute:

      chown -R prog.rtx .
chmod -R a+r,u+w,go-w .

  8. Log out as root and log in as prog

  9. cd /usr2/fs-tag

  10. make >&/dev/null

  11. make -s

    If there is no output from this command, then the make was successful.

  12. If you set the /usr2/fs link by using make install above, then reboot.

If this is a first time installation, you can then login as oper and run the FS, but you will need to customize the control files in /usr2/control before you can do anything useful. Additionally, you may need to add station software, particularly antcn if you want to control an antenna.

If this an update, you will need to follow the update instructions. There is usually a link to them in the release announcement, which can be found at https://nvi-inc.github.io/fs/releases/.

8. Managing testing of FS updates

TODO: develop and write

9. Users sending code changes to developer

TODO: patches? fork/pull-request?. It would be good to preserve commit SHAs for tracing versions using stations, if possible.