Process, edit and publish

The configuration files being used by the 'live' implementation of a system are referred to in a 'production' environment. Before a given configuration is published to production, is first developed in a 'dev' environment, and then tested in a stating environment. Additionally, you may have a training/ demo environment, which is a perfect replica of the production environment. The purpose of the training/ demo environment is to avoid affecting the usage stats of the real prod copy.

The diagram below shows the steps to take when a change is required in any of the C4C components. It details who is involved and in what instances or repositories the tasks should be performed. Following this process ensures that changes are properly vetted before deploying to production, avoiding misconfiguration from reaching production at any given time.

Storage

GitHub is a cloud-based repository used by millions of projects to host the source code and/ or release the product of the pertinent software. It provides version control using Git. It also provides access control and several collaboration features such as bug tracking, feature requests, task management, continuous integration, and wikis (like this one) for any project. For more information about GitHub, read here.

Branches

Each repository in GitHub has a main or default branch. Users with access to the repository can create multiple derivative branches. These other branches can later be merged to the main one by a pull request. In the SRH-C4C repository there are two branches:

Main

This branch is used only by the C4C technical administrator to store the original files: algorithm, questions, and exceptions.

Contributor

The Contributor branch can be edited by the C4C contributor team. Once the changes are done, the user can open a pull request, which means the desire to merge the changes from the Contributor branch into the main one.

To open the Contributor branch follow the steps below:

Access the psi-mis/SRH-C4C project on GitHub
Look for the branch icon and click to show the options.
Select the Contributor branch

How to edit a file

1. Select the file

2. Edit the file: the user can make changes directly on GitHub using the editor widget.

3. Save changes: To save the changes, the user will be forced to make a commit. Commits are composed of a title and a message in which the user is expected to describe what changes were made.

How to make a pull request

After the user has added changes to the contributor branch, he/she can open a pull request to ask the repository administrator to review the changes before merging them into the main branch. Follow the steps below:

Click on pull requests in the top menu bar
Click on "New Pull Request"
Select the "main" branch as the base and the "contributor" branch as the comparison.
All the commits will be shown for the user to check all the changes. Click on "create pull request"
Type a title and a description
Click on "create pull request"

Options for editing: using MS VisualStudio Code

Visual Studio Code is a source code editor available for Windows, macOS, and Linux. The tool supports Json, the syntax used for the C4C engine files. For more information, click here.

Setup

Review the visual studio code manual for setting up the tool:

To work locally in visual studio code, make sure to also download the GitHub Desktop tool.

How to edit a file in Visual Code

Download the file by clicking on the desktop icon.
In GitHub Desktop, select a location to clone the repository. All files will be downloaded.
Click on "Open in Visual Studio Code"
On the left panel, select the file to edit.
Verify the changes are being made in the contributor's branch.
After finishing the changes, save the file. (File --> Save or Ctrl.+S)