|
This How-To guide is for CR authors who are want to start drafting changes but don't yet have a CR number (and therefore can't start a [proper CR branch](How-To/Create-a-CR.md#make-a-new-CR-branch))
|
|
This How-To guide is for CR authors who are want to start drafting changes but don't yet have a CR number (and therefore can't start a [proper CR branch](How-To/Create-a-CR.md#make-a-new-CR-branch))
|
|
|
|
|
|
## Setting up the draft branch
|
|
## Setting up the draft branch
|
|
|
|
|
|
First, navigate to the [new branch](https://forge.etsi.org/rep/li/schemas-definitions/-/branches/new) page.
|
|
First, navigate to the [new branch](https://forge.etsi.org/rep/li/schemas-definitions/-/branches/new) page.
|
|
|
|
|
|
![New branch page](../img/new_branch.png)
|
|
![New branch page](../img/new_branch.png)
|
|
|
|
|
|
Set the details as follows:
|
|
Set the details as follows:
|
|
|
|
|
|
| Field | Description | Example |
|
|
| Field | Description | Example |
|
|
| -- | -- | -- |
|
|
| -- | -- | -- |
|
|
| Branch name | Start with `draft/` followed by something descriptive. A good convention to follow is using your initials and the spec you are drafting a change for| `draft/msc_103120` |
|
|
| Branch name | Start with `draft/` followed by something descriptive. A good convention to follow is using your initials and the spec you are drafting a change for| `draft/msc_103120` |
|
|
| Create from | Choose the [current meeting branch](Conventions/Branching-contentions.md), if available, otherwise `main` | `main` |
|
|
| Create from | Choose the [current meeting branch](Conventions/Branching-contentions.md), if available, otherwise `main` | `main` |
|
|
|
|
|
|
> If you create a draft branch from `main` rather than a current meeting branch, you may need to take some extra steps when you come to [turn your draft into a real CR](#convert-a-draft-branch-to-a-cr-branch). If at all possible, create from the latest meeting branch. If there is no current meeting branch, and you think there should be one, contact the [maintainers](Maintainers.md).
|
|
> If you create a draft branch from `main` rather than a current meeting branch, you may need to take some extra steps when you come to [turn your draft into a real CR](#convert-a-draft-branch-to-a-cr-branch). If at all possible, create from the latest meeting branch. If there is no current meeting branch, and you think there should be one, contact the [maintainers](Maintainers.md).
|
|
|
|
|
|
Then click "Create branch"
|
|
Then click "Create branch"
|
|
|
|
|
|
## Make changes as normal
|
|
## Make changes as normal
|
|
|
|
|
|
Make your changes [exactly like you would for a normal CR](How-To/Create-a-CR.md#make-your-changes), either via the Forge Web UI or via a local clone of the repository.
|
|
Make your changes [exactly like you would for a normal CR](How-To/Create-a-CR.md#make-your-changes), either via the Forge Web UI or via a local clone of the repository.
|
|
|
|
|
|
The CI/CD pipeline will still run after each commit, meaning that your draft changes will have the same ASN.1 and XSD checks run on them. This means that a draft branch can help you debug your schema changes while you are still drafting your CR.
|
|
The CI/CD pipeline will still run after each commit, meaning that your draft changes will have the same ASN.1 and XSD checks run on them. This means that a draft branch can help you debug your schema changes while you are still drafting your CR.
|
|
|
|
|
|
The preflight stage and the artefact generation stage are both skipped; for these to run you will have to wait until you have a proper CR with an Merge Request.
|
|
The preflight stage and the artefact generation stage are both skipped; for these to run you will have to wait until you have a proper CR with an Merge Request.
|
|
|
|
|
|
## Convert a draft branch to a CR branch
|
|
## Convert a draft branch to a CR branch
|
|
|
|
|
|
Once you have a CR number from the technical officer, you are ready to create a real CR branch.
|
|
Once you have a CR number from the technical officer, you are ready to create a real CR branch.
|
|
|
|
|
|
First, follow the instructions in the [Create a CR How-To](How-To/Create-a-CR.md), up to the point that you have created a branch and a Merge Request, but before you have made any changes.
|
|
First, follow the instructions in the [Create a CR How-To](How-To/Create-a-CR.md), up to the point that you have created a branch and a Merge Request, but before you have made any changes.
|
|
|
|
|
|
Then, create a Merge Request *from* your draft branch *to* your draft branch.
|
|
Then, create a Merge Request *from* your draft branch *to* your draft branch.
|
|
|
|
|
|
Create a Merge Request by going to the [Branches page](https://forge.etsi.org/rep/li/schemas-definitions/-/branches) and finding your draft branch. If you can't see it in the list, try typing some of the name, or the word `draft` into the search bar.
|
|
Create a Merge Request by going to the [Branches page](https://forge.etsi.org/rep/li/schemas-definitions/-/branches) and finding your draft branch. If you can't see it in the list, try typing some of the name, or the word `draft` into the search bar.
|
|
|
|
|
|
You will then be taken to the New Merge Request page.
|
|
You will then be taken to the New Merge Request page.
|
|
|
|
|
|
![Fill out the Merge Request correctly](../img/FillOutMRForm.png)
|
|
![Fill out the Merge Request correctly](../img/FillOutMRForm.png)
|
|
|
|
|
|
Fill it out as follows:
|
|
Fill it out as follows:
|
|
|
|
|
|
| Field | Value | Example |
|
|
| Field | Value | Example |
|
|
|-------|-------|---------|
|
|
|-------|-------|---------|
|
|
| Source (from) branch | Should already be set to your draft branch - leave this unchanged. | `draft/msc_103120` |
|
|
| Source (from) branch | Should already be set to your draft branch - leave this unchanged. | `draft/msc_103120` |
|
|
| Target (to) branch | **This is important:** This will be set to `main` be default, which is wrong. You **must set it this to your CR branch**. Click "change branches" at the top of the form, and set the "Target" branch to the correct plenary meeting branch. Then click "Compare branches and continue". | `cr/103120/123` |
|
|
| Target (to) branch | **This is important:** This will be set to `main` be default, which is wrong. You **must set it this to your CR branch**. Click "change branches" at the top of the form, and set the "Target" branch to the correct plenary meeting branch. Then click "Compare branches and continue". | `cr/103120/123` |
|
|
| Title | This isn't curcial, but ideally choose something that makes sense. | `Merging my draft CR into CR 123` |
|
|
| Title | This isn't curcial, but ideally choose something that makes sense. | `Merging my draft CR into CR 123` |
|
|
| Description | You can leave this blank. | |
|
|
| Description | You can leave this blank. | |
|
|
| Assignee | You can leave this unset | |
|
|
| Assignee | You can leave this unset | |
|
|
| Reviewer | Leave this unchanged | |
|
|
| Reviewer | Leave this unchanged | |
|
|
| Milestone | Leave this unchanged | |
|
|
| Milestone | Leave this unchanged | |
|
|
| Labels | Leave this unchanged | |
|
|
| Labels | Leave this unchanged | |
|
|
| Merge options - Delete source branch | Change this to **Yes**, unless you want to keep the draft branch for later work | |
|
|
| Merge options - Delete source branch | Change this to **Yes**, unless you want to keep the draft branch for later work | |
|
|
| Merge options - Squash commits | Change this to **Yes** unless you specifically need the commit history while you are working on the CR (commits in the CR will be squashed anyway)| |
|
|
| Merge options - Squash commits | Change this to **Yes** unless you specifically need the commit history while you are working on the CR (commits in the CR will be squashed anyway)| |
|
|
|
|
|
|
Click "Create Merge Request".
|
|
Click "Create Merge Request".
|
|
|
|
|
|
You should be taken to the merge request screen.
|
|
You should be taken to the merge request screen.
|
|
|
|
|
|
![Merge request screen](../img/newcr_mr_webide.png)
|
|
![Merge request screen](../img/newcr_mr_webide.png)
|
|
|
|
|
|
If you used the latest meeting branch as the basis for your draft branch, then you should see a "Merge" button. Click this, and all of the changes in your draft branch will be merged into your CR branch. You're now ready to continue work on your CR branch!
|
|
If you used the latest meeting branch as the basis for your draft branch, then you should see a "Merge" button. Click this, and all of the changes in your draft branch will be merged into your CR branch. You're now ready to continue work on your CR branch!
|
|
|
|
|
|
If you used `main` as the latest meeting branch, then you may find that your branch needs to be rebased before you can merge it. The Forge may be able to do this for you automatically; if so, there will be a blue "rebase" button. Click this, and once the rebase has completed, you should be able to click the "Merge" button as above.
|
|
If you used `main` as the latest meeting branch, then you may find that your branch needs to be rebased before you can merge it. The Forge may be able to do this for you automatically; if so, there will be a blue "rebase" button. Click this, and once the rebase has completed, you should be able to click the "Merge" button as above.
|
|
|
|
|
|
If the Forge can't rebase your branch, it will tell you so. At this point, you will either need to rebase or merge the branches yourself via the Git command line, or contact one of the [maintainers](Maintainers.md) to help you out.
|
|
If the Forge can't rebase your branch, it will tell you so. At this point, you will either need to rebase or merge the branches yourself via the Git command line, or contact one of the [maintainers](Maintainers.md) to help you out.
|
|
|
|
|
|
## Remove the draft branch
|
|
## Remove the draft branch
|
|
|
|
|
|
Once you are done with your draft branch - either because you have converted it to a regular CR, or you have decided not to pursue the changes, then remove the branch.
|
|
Once you are done with your draft branch - either because you have converted it to a regular CR, or you have decided not to pursue the changes, then remove the branch.
|
|
|
|
|
|
If you selected "Delete source branch" in your MR options, then this will have been done automatically once you merged the changes into your CR branch.
|
|
If you selected "Delete source branch" in your MR options, then this will have been done automatically once you merged the changes into your CR branch.
|
|
|
|
|
|
If you did not, or you didn't progress to a CR, then navigate to the [branches](https://forge.etsi.org/rep/li/schemas-definitions/-/branches) page, find your draft branch, and select "delete".
|
|
If you did not, or you didn't progress to a CR, then navigate to the [branches](https://forge.etsi.org/rep/li/schemas-definitions/-/branches) page, find your draft branch, and select "delete".
|
|
|
|
|