This guide gives step-by-step instructions for creating a CR using the Forge.
- Before you start
- Go to the repository page
- Make a new CR branch
- Create a Merge Request
- Make your changes
- See if it passes the tests
Before you start
Before you start, you will need:
- To have logged in to the Forge
- To be a member of the project
- To have got a CR number from the 3GPP Portal
Go to the repository page
Go to the Forge repository.
Make a new CR branch
The first step is to create a branch 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 button in the top right of the page.
The New branch page allows you to specify details for your new branch. Fill in the fields as follows:
|Branch name||Follow the branching convention and choose a name of the form
|Create from||Pick the branch for the plenary meeting that will eventually approve the CR (e.g.
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 or contact a Maintainer for help.
Create a Merge Request
Before you make any changes, it is important to make a Merge Request. 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 to work.
Create a Merge Request by going to the Branches page 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 correctly, it should appear.
Once you've found it, hit the "Merge Request" button.
Fill in the Merge Request form following the Merge Request conventions:
|Source (from) branch||Should already be set to your CR branch - leave this unchanged.||
|Target (to) branch||
This is important: This will be set to
|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 to help you.
Make your changes
You can now start making changes that you want to make.
To do this, go back to the Repository page and make sure that you are on the right branch by checking the branch drop-down just under the navigation links.
To make changes, navigate to the file that you'd like to make changes to, by selecting the correct deliverable (e.g 33128) and release (e.g r17), and then picking the artefact that you want to change (e.g. TS 33128Payloads.asn). If your CR touches multiple ASN.1 modules or XSD schemas, then edit each one in turn - each CR/MR can contain changes to multiple files.
When clicking on files, make sure you click on the left-hand part of the table, under "Name". If you click on the column labelled "Last commit", it will take you to the last commit which changed that part of the repository. This is very useful for lots of things, but not for what you are trying to do!
When you select the file, you will be presented with the current version of the file. You can edit it by clicking on the "Edit" button near the top right of the page. Doing so will enter the editor, where you can make whatever changes you wish.
There are many other ways of making changes to a file. You could use the Web IDE, or making a local clone of the repository on your computer and use the development tool of your choice. If you are comfortable doing that - go for it! es Once you are happy with the changes you've made, you need to commit them. To do this, you need to fill in the fields at the bottom of the editor and hit "Commit changes". But it is important to fill the fields out correctly!
Once you have made your changes, scroll to the bottom of the screen. If you find it is taking a long time to reach the bottom, and you are scrolling through a lot of ASN.1, check you are using the right scroll bar! You want the outermost one.
Once you reach the bottom, you will find the "Commit changes" button, along with some additional information.
|Commit message||This is a free text message that you can use to explain your changes to other people (including Future You). The Forge will automatically populate this with a suggestion, but if possible replace it with something short and descriptive.|
|Target branch||If you selected the right branch earlier, this should already be populated with the name of your CR branch. If it isn't you need to change it - click on the box and select your branch from the drop-down list.|
Once you are ready, click the "Commit changes" button. If you decide that you want to discard your changes, click "cancel", or simply navigate away from the page.
See if it passes the tests
Now you have commited your change, other people can see and comment on it. The Forge will now run a set of automated checks on the changes you've made. 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.
The symbol tells you what is happening with the test.
|The tests are waiting to be added to the queue|
|The tests are in the queue to be run|
|The tests are running|
|All the tests passed|
|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 3GPP specifications still have to go through the 3GPP 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 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.
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
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.
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
Once your CR is accepted, the rapportuers and maintainers will handle integrating your changes in to the specification.