1. (MODAClouds) Software repositories

This document is a draft!

1.1. Hosting

The following public repositories were prepared for the usage by the MODAClouds consortium members. These repositories are mainly meant to cover those software components whose primary versioning system is either Git or Mercurial.

As hinted above all these repositories are public, thus only the open-source software components should be hosted in these repositories!

The supported versioning systems are:

The choice between GitHub or BitBucket, and between Git or Mercurial, is left open to each consortium member, especially since some software components are already hosted in one or the other variants. Moreover it is not mandatory for a software component to be hosted in one of these accounts. However if a partner does want to migrate from an existing SVN repository to either Git or Mercurial, while still keeping the history of the code (i.e. a complete migration), we can provide support.

Describe the possibility of mirroring.

  • automatic mirroring from other Git or Mercurial repositories hosted somewhere else;
  • automatic import (with history) from existing SVN repositories;

Describe the status of the internal SVN repository.

1.1.1. Repository types "Account" repositories

The actual user account should be used only for: "Organization" / "team" repositories

The organization / team accounts should be used only for:

For distinguishing between the two sets of repositories we shall use the following terminology: "Individual" repositories

However many of the MODAClouds consortium members already have independent repositories under other accounts (personal, institutional, or per-project). These should be considered equivalent to the development or collaborative repositories. Thus in case some of the software components are already hosted inside these "individual" accounts, the usage of the experimental or collaborative repositories is completely optional, and encouraged only when multiple developers (with different affiliations) work on the same repository. Therefore in the case only one developer is maintaining a repository, he can keep it under the "individual" account. "Mirror" repositories

Should we keep mirrors (and where) for those third-party software components which although are used "as-provided", have a high risk of "disappearing" (e.g. being deprecated by their developers and removed or renamed) or having "unstable code histories" (i.e. non-forward pushes, history rewriting, etc.)?

(These "mirror" repositories, which are for third-party software components, should not be confused with MODAClouds repository mirrors.)

1.1.2. Creation and access

For the "official repositories" (i.e. the actual user accounts) the following steps are proposed:

For the "experimental or collaborative repositories":

To summarize:

Obviously anyone (including anonymous Internet users) can download the source code of any repository, either within the "official" or "experimental / collaboration" repositories.

1.2. Guidelines

1.2.1. Naming

All the repositories should follow these naming conventions:

1.2.2. Branches

Within the context of this section the following conventions are made:

For any software component hosted in one of these repositories, the "main branch" should always contain the latest stable source code for that particular component (i.e. the current "main branch" should always have an accompanying version tag). This ensures that any checkout by an unadvised user results in at least clean and compilable code (and at best the latest usable code).

Any development, including maintenance for already stable versions --- thus called development lines --- should be made in other branches than the "main branch". Thus updating the "main branch" --- which as described above represents the latest stable version --- depending on the used versioning system, is done by:

However the previous techniques tackle only the situation when a single development branch is active for a particular software component (i.e. the "main branch"), and requires that any new versions are strictly developed on-top of the previous versions. Thus only sequential versions are possible (e.g. starting with v0.1.0, followed by v0.1.1, followed by v1.0.0, then v1.0.1, v1.1.0, v1.1.1, v2.0.0, etc.), and parallel releases are impossible (e.g. v2.0.0 followed by v2.0.1 in parallel with v1.5.0 followed by v1.5.1, etc.) The solution in such a situation again depends on the versioning system:

As naming conventions the following could be applied:

The reason why in Mercurial the branches are always named bX.Y, regardless of their status, is because branch names are immutable. (As opposed to Mercurial bookmarks or Git branches which are just pointers to a particular commit.)

It should be debated if the "main branch" should contain the source code that is part of the latest MODAClouds release, as opposed to the latest component release (e.g. the source code for the component at the latest version (say v2.0) could be newer than the source code for that component at the version (say v1.5) that was embedded in the latest MODAClouds release, thus the two could be incompatible). However because some components are shared between multiple projects, such a policy cannot be enforced. But the question still stands for the other MODAClouds-only components.

1.2.3. Tagging

The following types of tags should be present in all repositories:

version tags

prefixed with v and compatible with "Semantic Versioning" (http://semver.org/), used only for stable releases of that component; (e.g. v0.1.0, v2.1.3, etc.;) (the version "trees" are independent between various components within the MODAClouds ecosystem, and a similar version number does not imply any relation or compatibility between the two different components;)

snapshot tags

prefixed with s and followed by a date in the format YYYY-MM-DD, used only as internal reference points during development and collaboration (i.e. these versions should not be considered "released" or "stable"); (e.g. s2014-02-10, etc.;) (in the extremely rare case when two snapshots are made in the same day a letter suffix is added to the tag, such as -a;)

release tags

prefixed with modaclouds-r and followed by the version of the actual MODAClouds release, used to mark the version of the code which was included (or used) in a particular release; (e.g. modaclouds-r1.0.0, etc.)

Except the snapshot tags, both the version tags and the release tags are to be considered immutable and once created they should not be removed or changed. On the other hand the snapshot tags imply no commitment and (although inadvisable) they can be changed or removed.

Moreover it is advisable that each tag is cryptographically signed by the lead developer, and the tag message should contain a short description of the changes featured by that particular version (as opposed to the ancestor).

The release tags could have been prefixed only with r (e.g. r1.0.0), however in the case a component is used in multiple projects, and the same repository is used, then adding the project name as a prefix eliminates any ambiguity. (For example the mosaic-node repository was referenced in a few mOSAIC releases, is currently referenced in the MODAClouds releases, and could in future be referenced in SPECS releases. Such a release tagging scheme allows the same repository to hold the tags for all these projects, without any conflicts. Furthermore it can help to differentiate between the various variants and enhancements made between the three distinct projects.)

1.2.4. Required files

In each of the repositories there must be the following files: Read-me file

In the root of the repository there should be a "read-me" file, which should contain the following details:

Furthermore the read-me file can contain other useful information such as:

The name of the read-me file should be either README.* or readme.* (i.e. either all upper-case or all lower-case letters, followed by an extension).

The format of the read-me file should be one of the following:

To be written!

Add a template for the read-me file. Notice file

In the root of the repository there should be a notice file, which should contain the following details:

In addition to the mandatory information above, the notice file could also contain:

The name of the notice file should be either NOTICE.TXT or notice.txt, and its format should be plain text (i.e. without heavy markup languages).

To be written!

Add a template for the notice file.

1.2.5. Repository layout

Except for the two required files described above (i.e. the "read-me" and the "notice" file), each repository should abide to the best-practices of the programming language / environment / framework of the project.

However the following generic guidelines could be applied: Repository examples

To be written!

Add an example for a Java project handled trough Maven. Script files

To be written!

Describe the files that should be present in the scripts folder, which would ease the integration process.

1.2.6. Miscellaneous

To be written!

  • file naming best practices;
  • executable files;
  • binary files;
  • archived files;

1.3. Workflows

To be written!

  • cloning third party repositories within the official repositories;
  • cloning of official repositories by developers;