This is a template repository to be used as the base for all new repos created for the Agile Methods training course (by a course facilitator). It comes with a set of default issues, types and settings to ensure a standardised setup.
The following steps will need to be performed immediately after creating the new repository to complete the set up.
Defining and linking a Project to this repository should be performed as part of the initial setup on the course. Learners should be instructed to use the Agile Methods Training template project to set this up.
This README should be changed by the course facilitator to leave any instructions that are part of the course learning, and other elements should be deleted before passing the repository on to the learners.
The first thing to do after creating your new repository from this template is to head to Settings -> Rules -> Rulesets then choose Import Ruleset. You will then need to import the Key Branch Protection Rules.json ruleset which is located in the RSE Team SharePoint under RSE Team -> Read-Only -> Tools.
This ruleset is designed to enforce a GitFlow development process as per the department policy. Please do not relax or disable these rules unless exceptional circumstances dictate it e.g. if an existing CI integration requires a rule to be relaxed.
If you use this template outside of the UoMResearchIT organisation, you should instead delete the check-ruleset.yaml workflow, as it cannot run successfully (due to its security configuration). You are still expected to adopt the ruleset listed above; it's just not automatically enforced.
In order to streamline the learning in the requirements gathering chapter, some issues relating to the product have already been created in the template repository. To copy these issues from the template into the new repository that the learners are going to use, please run the copy-issues workflow from the Actions tab in the new repository.
Our team policy on software licensing and copyright can be found in the RSE_Department_Ops_Policies.pdf document, located in the RSE Team SharePoint under RSE Team -> Read-Only -> Policies and Processes. This policy is summarised below for convenience. If any discrepancies between the two arise then the policy document takes precedence over this readme file.
The default licence for an RSE project is the Apache v2.0 licence, a copy of which is provided in the file LICENSE. The customers licensing preference should have been gathered during the requirement gathering stage of the project; ask your project manager if this differs from the default.
Unless the project owners have made other agreements, the copyright of all works belongs to the University of Manchester. Check with your project manager to ensure that this is the case. Guidance on copyright issues are available from the University of Manchester library.
To state the copyright, and use the Apache v2.0 licence, you should include the following text as a comment at the head of every source file you write:
SPDX-FileCopyrightText: [yyyy] University of Manchester
SPDX-License-Identifier: apache-2.0
Replace [yyyy] with the year that the code was first written. The License Identifiers that are supported can be found in the SPDX License Documentation.
In files which do not support the addition of comments (such as binary files), this can instead be included in an additional file adjacent to the original file with the same name followed by a .license extension, and containing just the lines above (e.g. a file called cat.jpg would have a licence file cat.jpg.license).
Note that there is a GitHub action in this repository that will check that all files have the above annotations or .license file associated with them. If this fails, an additional branch will be created which can be merged into the changes that you have committed. A link will appear in the outputs of the GitHub actions task that will allow you to create a PR and merge this into your branch to allow the test to pass. This link will also be added as a commit comment, which will be e-mailed to you if you have GitHub set up to send you notifications in this way. You should check the details of the suggested changes carefully to ensure it has done the right thing; any corrections can be made before merging, or can be done manually in the original branch if preferred.
If the licence and/or copyright differs from the default, the action will have to be updated to reflect this. Please edit the reuse-action in .github/workflows/license-copyright-add.yml to fix it, using the appropriate identifier from the SPDX License List.
If the GitHub Action doesn't recognise a file format, it will generally add a .license file. If you would prefer the license information to go into the file and you think it should be recognised, you can update the .extraformats file in the root of the repository with this information. This file is formatted as a JSON dictionary, with the key being the filename or wildcard to match, and the value being one of the formats (see below for a list of formats supported). For example, the following will recognise files with a cwl extension, and requirements.txt as python files, and so expect comments and put comments in using the python comment style:
{
"*.cwl": "python",
"requirements.txt": "python"
}
Note that this will look at the filename only, and won't work if you try to add a folder into the path. If you wish to add specific files (or wildcards) within folders, just put the filename.
If there are files that should not have a license on them and can therefore be ignored, the .licenseignore file in the root of the repository can be edited. This follows the same standard as the .gitignore file format.
Note
This should usually only be used for generated files that nonetheless need to be checked into the repository, where there's no reasonable human-input in their creation. Almost all files should have a copyright notice.
The following is a list of formats that you can put in the .extraformats file for recognition by the license annotation tool:
aspxbatbibtexblazorccppcppsingledjangoff90ftlhandlebarshaskellhtmljinjajulialispm4mlplantumlpythonrstsemicolontexmanvstvimxquery
If there's a comment format that isn't supported, file a PR. Adding formats is fairly easy.
Setup .gitignore according to your project needs, see .gitignore templates here.