Branches allow the Forge to manage different versions of the repository in parallel. Our branching convention puts each CR in a branch of its own.
Select "Repository" from the menu on the left-hand side of the page, and select "Branches".
Step 3 - Make a new branch for your CR
Create a new branch for your CR by clicking the "New Branch" button in the top right of the page.
Step 4 - Supply details for your new branch
The new branch page allows you to specify details for your new branch. There are two fields to fill in, "Branch name" and "Create from". Fill these in and hit the "Create branch" button.
In principal this can be anything as long as it is unique within the repository. However, it will help others if you follow the branching convention and choose a name of the form r[X]/cr/[your CR number or name]
If need to rename your branch this is only possible using command line, in Github you can delete the branch and start again or contact a Maintainer for support.
This sets the version that your branch will be a copy of. Click on the item to see a drop down list. It is a good idea to choose the relevant branch for the meeting (i.e. r[X]/meeting/[meeting number]). If you can't find the right branch, contact one of the maintainers
Step 5 - Make some changes!
You now have a branch that is specific to your CR. 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 drop-down near the top left of the page.
To make changes, simply click on a file that you'd like to make changes to. 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!
Step 6 - Commit your changes
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!
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.
This one is important. You need to make sure you commit your changes to the branch you created earlier. If this isn't set correctly, click on the box and select your branch from the drop-down list.
Now you have commited your change, other people can see and comment on it. The Forge can also 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 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.
If the icon does not show immediately refresh the webpage.
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 steps 5 and 6 as often as you need until you are happy that you can propose your CR.
Step 7 - Create a Merge Request
Once you are happy with all of your changes, create a Merge Request. This is a request for all the changes in your branch to be merged with one of the parent branches. It is possible to make Merge Requests (or "MRs") between any two branches, but we will be following our branching convention and making the request to merge your CR branch with the meeting branch.
Create a Merge Request by going to the repository page and clicking on the "Merge Request" button.
There are a lot of fields that can be filled in. These are described in more detail in the Merge Request conventions, but the most important are as follows:
This sets the branch that you want to merge with. The Forge will automatically populate this with the default branch, but this is typically not what we want. First, click the "change branches" link to the right of the box.
In the following page choose the correct meeting branch in the "Target branch" drop down on the right. Click "Compare branches and continue".
Delete source branch when merge request is accepted
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
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