gsc repositories - GeoSmartCity-CIP/gsc GitHub Wiki

Working with gsc-repositories

This document describes the Git repositories conventions within the GSC project. All repositories must provide the following pieces of information:

  • Purpose of the repository.
  • Source code
  • Development requirements and how to contribute.
  • Releases information.
  • Install or usage instructions.
  • How to evaluate the operation of the developed component.

Two types of repositories are distinguised:

  • New. Started from scratch repositories.
  • Forks. From existing projects.

All repositories will be catalogued in the readme file included in the main GSC repository. For New repositories the catalog will point to the Readme file of the repositories. In the case of Forks, it will point to a specific documenting file which will be stored within the /docs folder.

Documenting new repositories

Minimal required folder structure:

  • /readme.md: purpose of the repository, description, and links to the remaining docs:
  • /.gitignore
  • license.txt
  • /docs/releases.md: info about each release.
  • /docs/contributing.md: how to develop and contribute.
  • /docs/install.md: how to deploy, install or use.
  • /src or /name_of_repository: source code.
  • /tests (or /src/tests)

Typical items:

  • /.travis.yml
  • /docs/usage.md
  • /tools
  • lint config
  • project config

Programming languages specific conventions

Documenting forks

Forks will use existing conventions of master project.

In order to have specific in porject information, a name-of-forked-project.md file will be added to main GSC repository, below /docs folder.

This file will include the following sections, conveying the same information than new repositories:

  • General description and purpose: it will describe extensions to parent project.
  • Contributing: other than master project considerations.
  • Releases: internal to gsc releases.
  • Install: other than master project considerations.

Release conventions

The tagging of releases will adhere to Semantic Versioning conventions. Versions will be tagged in one of the following two forms:

  1. MAJOR.MINOR.PATCH-TAG.TAGNUM

  2. MAJOR.MINOR.PATCH

Changes in:

  • MAJOR: means backwards incompatible.
  • MINOR: means new features backwards compatible.
  • PATCH: means corrections to current features.

TAG will be one of:

  • alpha: Prototype. Only some features implemented. Not deployable.
  • beta: Most features implemented. Deployable in custom infrastructure. Testable by devs.
  • rc: All features implemented. Deployable in GSC infrastructure. Testable by users.
  • none: production versions.

Samples:

  • 1.2.0 Features have been added to a component that users are happily using in production.
  • 1.0.0-rc.2: Integrating in the hub. Users are testing the features.
  • 0.6.0-beta.1: a lot of features have been implemented that are being tested.
  • 0.5.0-alpha.4: in development. Prototype may be shown.