|
|
# Overview
|
|
|
This guide gives step-by-step instructions for creating a CR using the Forge.
|
|
|
|
|
|
- [Overview](#overview)
|
|
|
- [Before you start](#before-you-start)
|
|
|
- [Go to the repository page](#go-to-the-repository-page)
|
|
|
- [Make a new CR branch](#make-a-new-cr-branch)
|
|
|
- [Create a Merge Request](#create-a-merge-request)
|
|
|
- [Make your changes](#make-your-changes)
|
|
|
- [See if it passes the tests](#see-if-it-passes-the-tests)
|
|
|
- [Draft the CR form](#draft-the-cr-form)
|
|
|
- [Next steps](#next-steps)
|
|
|
|
|
|
# Before you start
|
|
|
Before you start, you will need:
|
|
|
|
|
|
* To have [logged in to the Forge](How-To/Log-in)
|
|
|
* To be a [member of the project](How-To/Join-a-project)
|
|
|
* To have got a CR number from the TC LI Technical Officer
|
|
|
|
|
|
# Go to the repository page
|
|
|
Go to the [Forge repository](https://forge.etsi.org/rep/li/trial).
|
|
|
|
|
|
From there you need to go to the [Branches page](https://forge.etsi.org/rep/li/trial/-/branches). Select "Repository" from the menu on the left-hand side of the page, and select "[Branches](https://forge.etsi.org/rep/li/trial/-/branchess)".
|
|
|
|
|
|
![Go to the Branches page](../img/GoToBranches.png)
|
|
|
|
|
|
# Make a new CR branch
|
|
|
The first step is to create a [branch](Conventions/Branching-convention) for your CR. Think of it as the contents of your CR - it's your own special working copy of the repository where you make your changes.
|
|
|
|
|
|
Create a new branch for your CR by clicking the [New branch](https://forge.etsi.org/rep/li/trial/-/branches/new) button in the top right of the page.
|
|
|
|
|
|
![Make a new branch](../img/MakeANewBranch.png)
|
|
|
|
|
|
The [New branch](https://forge.etsi.org/rep/li/trial/-/branches/new) page allows you to specify details for your new branch. Fill in the fields as follows:
|
|
|
|
|
|
| Field | Value |
|
|
|
| -- | -- |
|
|
|
| Branch name | Follow the [branching convention](Conventions/Branching-convention) and choose a name of the form `cr/{deliverable/{CR number}` |
|
|
|
| Create from | Pick the branch for the **plenary** meeting that will eventually approve the CR (e.g. `meeting/LI61`) |
|
|
|
|
|
|
> If you mess up, don't panic. You can't rename branches, but you can delete the branch you just created and try again. If you have changes you don't want to lose, you can use a [command line trick](Rename-a-Branch) or contact a [Maintainer](Process/Maintainers) for help.
|
|
|
|
|
|
# Create a Merge Request
|
|
|
Before you make any changes, it is important to make a [Merge Request](Conventions/Merge-Request-convention). Think of it as the Forge equivalent to the coversheet on your CR form - it tells the Forge what you actually want to make changes to, and it's needed to keep track of changes and for the [automated testing](Process/Automated-checking) to work.
|
|
|
|
|
|
Create a Merge Request by going to the [Branches page](https://forge.etsi.org/rep/li/trial/-/branches) and finding the branch you just created. If you can't see it in the list, try typing your CR number into the search bar at the top. If you followed the [branching convention](Conventions/Branching-convention) correctly, it should appear.
|
|
|
|
|
|
Once you've found it, hit the "Merge Request" button.
|
|
|
|
|
|
![Find your branch and create a merge request from it](../img/CreateMR.png)
|
|
|
|
|
|
Fill in the Merge Request form following the [Merge Request conventions](Conventions/Merge-Request-convention):
|
|
|
|
|
|
| Field | Value | Example |
|
|
|
| ----- | -- | -- |
|
|
|
| Source (from) branch | Should already be set to your CR branch - leave this unchanged. | `cr/33128/0987` |
|
|
|
| Target (to) branch | **This is important:** This will be set to `main` be default, which is wrong. You **must change it** otherwise it will cause issues for the TO and automated testing. Click "change branches" and set the "Target" branch to the correct plenary meeting branch.| `meeting/SA94e` |
|
|
|
| Title | `{Deliverable} CR {CR number} - {Title of your CR}` | `TS 33.128 CR0987 - My First CR` |
|
|
|
| Description | A human readable description of your change. We suggest using the abstract or "reason for change" from your CR coversheet. | |
|
|
|
| Assignee | Click the "Assign to me" button to assign the MR to yourself | @canterburym |
|
|
|
| Milestone | Leave this unchanged | |
|
|
|
| Labels | Leave this unchanged | |
|
|
|
| Merge options - Delete source branch | Change this to **No** ||
|
|
|
| Merge options - Squash commits | Change this to **Yes** ||
|
|
|
|
|
|
Once you're done, click the "Submit merge request" button
|
|
|
|
|
|
|
|
|
> If you make a mistake here, don't worry - you can always come back and edit it later, or get one of the [Maintainers](Process/Maintainers) to help you.
|
|
|
|
|
|
|
|
|
![Fill out the Merge Request correctly](../img/FillOutMRForm.png)
|
|
|
|
|
|
# Make your changes
|
|
|
You can now start making changes that you want to make.
|
|
|
|
|
|
There are many different ways to do this. One of the simplest is to use the Forge's Web IDE (Integrated Development Environment). You can open this IDE from your Merge Request page, by clicking on the "Open In Web IDE" button just under your Merge Request description.
|
|
|
|
|
|
![Opening the web IDE](../img/newcr_mr_webide.png)
|
|
|
|
|
|
CLicking this button will open the Web IDE in your CR branch. This means that changes you make will be contained within your branch and not disturb anything else.
|
|
|
|
|
|
![The Web IDE](../img/web_ide.png)
|
|
|
|
|
|
Use the left-hand pane to select the file you want to edit, and then make whatever changes you need to. If your change requires modifications to multiple schemas, then you can edit multiple files. Once you're ready, click the blue "commit" button in the bottom-left corner.
|
|
|
|
|
|
This will open up the commit message box. If you want, you can write a little message to explain what you are changing, but it isn't mandatory. By default, the dialog should be set to commit the changes to your CR branch.
|
|
|
|
|
|
![The Commit message box](../img/commit_message.png)
|
|
|
|
|
|
> If this message box defaults to creating a new branch with a long and complicated
|
|
|
> name with the word "patch" in it, then you have gone wrong somewhere. This means that
|
|
|
> you are making changes to a protected branch; either `main` or the meeting branch, rather than your CR.
|
|
|
> You can still commit the change (nothing bad will happen) and it's easy to move
|
|
|
> the change into the right branch, but but you'll need to contact
|
|
|
> your friendly neighbourhood Forge expert to help you.
|
|
|
|
|
|
Once you have committed your changes, you will be left in the Web IDE. If you want to make more changes (and more commits), you can do so.
|
|
|
|
|
|
You don't have to make all your changes in one go; you can make as many commits as you want. Indeed, good development practice often calls for commits to be "little and often" as it makes it easier to undo specific things later if you need to. But it's your CR - if you want to make all your changes in one big commit, go for it. No one is judging you.
|
|
|
|
|
|
|
|
|
# See if it passes the tests
|
|
|
Now you have commited your changes, other people can see and comment on them. The Forge will now run a set of automated checks on the changes you've made. Go back to your Merge Request page and look out for a little icon that tells you whether your commit has passed these checks or not. If you can't see it, refresh the page.
|
|
|
|
|
|
![CI/CD icon](../img/cicd.png)
|
|
|
|
|
|
The symbol tells you what is happening with the test.
|
|
|
|
|
|
| Symbol | Meaning |
|
|
|
| -- | -- |
|
|
|
| ![CI/CID Pending](../img/pipeline_waiting.png) | The tests are waiting to be added to the queue |
|
|
|
| ![CI/CID Pending](../img/pipeline_pending.png) | The tests are in the queue to be run |
|
|
|
| ![CI/CID Pending](../img/pipeline_running.png) | The tests are running |
|
|
|
| ![CI/CID Pending](../img/ci_pass.png) | All the tests passed |
|
|
|
| ![CI/CID Pending](../img/pipeline_fail.png) | One or more of the tests failed |
|
|
|
|
|
|
If it fails, click on the icon to find out more about why it failed. You will also receive an email notification containing a link to the failed commit.
|
|
|
|
|
|
> The automated checks are a work in progress. They may not always work,
|
|
|
> and they may not catch every error. You should always check your changes
|
|
|
> with a suitable compiler or tool.
|
|
|
|
|
|
If you need to make further changes, repeat the previous steps as often as you need until you are happy that you can propose your CR. You can make as many commits as you like in your CR branch.
|
|
|
|
|
|
|
|
|
## Draft the CR form
|
|
|
Changes to ETSI specifications still have to go through the ETSI change control procedure, even if the changes are held on the Forge. But your CR can now refer to the Forge for any changes to the machine deliverable parts, rather than writing them out in a change-marked Word document.
|
|
|
|
|
|
To do this, you need the [commit hash](https://blog.thoughtram.io/git/2014/11/18/the-anatomy-of-a-git-commit.html) of the change you want to make. This is a unique and durable identifier of the changes in the Forge that you want to refer to. It allows anyone, at any point in the future, to refer back to exactly the changes you intend.
|
|
|
|
|
|
The commit hash turns up in lots of places. If you have just made a Merge Request, then you can find it at the bottom of the form (under "commits") or next to the CI/CD pipeline report near the top.
|
|
|
|
|
|
![Commit hash](../img/commithash.png)
|
|
|
|
|
|
Copy this hash and refer to it in the "Comments" section of your CR.
|
|
|
|
|
|
> Even better, copy the URL associated with the commit hash.
|
|
|
> Click on either the link in the CI/CD pipeline report or on the title of the latest commit in the "commit" section.
|
|
|
> This takes you to a page that displays the commit.
|
|
|
> Referencing the URL in the CR form makes it easy for readers to see your changes
|
|
|
|
|
|
For more information, see [CR form conventions](Conventions/CR-form-conventions)
|
|
|
|
|
|
## Next steps
|
|
|
You now have a CR and a related Merge Request on the Forge. Your change can be considered by the meeting. What happens now?
|
|
|
|
|
|
You and others may well want to make changes to your CR based on discussions before approval. See [Making changes to a Merge Request](Making-changes-to-a-Merge-Request).
|
|
|
|
|
|
In some cases you may find that your Merge Request - while perfect in it's own right - needs to be updated to deal with a merge conflict due to someone else's CR being accepted first. See [dealing with Merge Conflicts](Dealing-with-Merge-Conflicts)
|
|
|
|
|
|
Once your CR is accepted, the rapportuers and maintainers will handle [integrating your changes](Merging-changes-as-a-rapportuer) in to the specification. |
|
|
\ No newline at end of file |