This Markdown Specification project implements an example of a structure to store and collaborate on a 3GPP specification in a git repository. The base version of the specification is v18.0.0 of TS38.331. The example recreates the RILs for the UAV work item starting in RAN2#125. The RILs are named as they were in that reivew, the review file for which can be found linked below in the resources section. The RILs were recreated to closely match their corresponding edits to the frozen specification, as if each RIL were submitted with text proposals for changes. The RILs were then implemented through merges and merge conflict resolution.
This Markdown Specification project implements an example of a structure to store and collaborate on a 3GPP specification in a git repository. The base version of the specification is v18.0.0 of TS38.331. The example recreates the RILs for the UAV work item starting in RAN2#125. The RILs are named as they were in that review, the review file for which can be found linked below in the resources section. The RILs were recreated to closely match their corresponding edits to the frozen specification, as if each RIL were submitted with text proposals for changes. The RILs were then implemented through merges and merge conflict resolution.
# Git
To get started with the basics of Git, it is recommended to read the [documentation](https://git-scm.com/book/en/v2). The most important sections to check are "Getting Started" and "Git Basics". For most, the following Git commands will be the most useful.
| Command | Function |
|----|----|
| git status | Print the status of the files in the git repository. Staged (added for commit) and unstaged files will be listed. This view is a good way to verify that all the intended files have been added prior to committing changes to ETSI Forge. |
| git branch | Print all of the branch names associated with the repository. Add -v, i.e., git branch -v, to show the latest commit message for each branch. |
| git checkout \<branch\> | Switch to branch `<branch>` |
| git checkout -b \<branch\> | Create a branch `<branch>` and swich to it. |
| git add <filename> | Add a file to the staging area for committing to the repository. It is best practice to specify each file separately. Never try to use the -a flag to add everything at once. |
| git commit | Commit staged (added) files to the repository. Without arguments, a text editor will launch where a commit message can be written. |
| git commit -t <template> | Commit staged (added) files to the repository. A text editor will open with the text of the specified template `<template>`, to be filled in. |
| git commit -m <message> | Commit staged (added) files to the repository with the commit message `<message>`. |
| git fetch | Retrieve the latest changes from the remote repository, including all new branches and modifications to existing branches. |
| git push origin \<branch\> | Push the committed changes of branch `<branch>` to the remote repository. |
It is important to ensure that the changes, which are first committed locally, are as intended prior to pushing changes to the repository. The following example shows a typical procedure for proposing changes to a file. The company name, which could eventually be a simpler identifier, is included as part of the branch name to avoid conflicts. The example is using Git BASH. Lines starting with \$ identify commands issued by the user. Lines starting with \> identify command outputs, and all other text is explanatory.
> Radio Resource Control (RRC) protocol specification
>
> (Release [-18)-]{+19)+}
>
> ---
```
Check the status after modifying the file. Note that it is modified, but not staged for commit.
```
$ git status
> On branch General_Nokia_spec_version
> Changes not staged for commit:
> (use "git add <file>..." to update what will be committed)
> (use "git restore <file>..." to discard changes in working directory)
> modified: 38331-i00.md
```
Add the file to be committed.
`$ git add 38331-i00.md`
Check the status after modifying the file. Note that it is shown as "to be committed".
```
$ git status
On branch NR_AIML_Air-core_Nokia_applicability_report
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: 38331-i00.md
```
Once satisfied with the changes, commit the changes with a message.
`$ git commit -m "Updated specification version to 19, v19.0.0."`
Push the branch to ETSI Forge.
`$ git push origin General_Nokia_spec_version`
# RILs
RILs are comments or direct suggestions for changes to a frozen release under review. Historically, RILs were written such that they would point to a specific example in the specification, with discussion that changes should apply to each relevant section of the specification. However, the RILs for this project have been created differently. Here, the RILs are able to modify related text throughout the specification as to propose a full set of common changes at the same time. For example, procedural text related to releasing configurations might need to be updated in several parts of the specification to address the same issue. One RIL could implement the chagnes all at once.
...
...
@@ -20,6 +111,8 @@ The following structure has been developed for the demonstration. It is a first
As is demonstrated by the structure, RILs are submitted independently from one another and are merged in as they are agreed. Branches can derive from other branches, creating a hierarchy. Because the branches were based on the clean specification, the final set of changes are fully compatible with the clean specification and can be merged in as a set.
Check the [repository graph](https://forge.etsi.org/rep/fevold/markdown-specification/-/network/main?ref_type=heads) for a visualization of the branches and how they were merged into the implementation branches, impl_v0, impl_v1, and impl_v2.
