diff --git a/Workflow for documentation production in OSM.md b/Workflow for documentation production in OSM.md index 9c64f4773b97fc8b2d4cbd85857a79560ccf3bba..d756a4cb840d4ffc1dc373bb8906e70550e49247 100644 --- a/Workflow for documentation production in OSM.md +++ b/Workflow for documentation production in OSM.md @@ -109,7 +109,7 @@ git clone git@osm.etsi.org:osm-doc/test.git git clone https://osm.etsi.org/gitlab/osm-doc/test.git ``` -#### If the repository already exists in ETSI's Gitlab and the local copy it is not up-to-date +#### If the repository already exists in ETSI's Gitlab and the local copy is not up-to-date ```bash git pull origin master @@ -129,7 +129,7 @@ Then create a branch and move to it in order to continue. In this example, we wi git checkout -b BranchNewSection ``` -#### NOTE: What to do if you committed changes to master by mistake +#### NOTE: What to do if you committed changes to `master` by mistake In case you forgot to create your branch (or moving to it) and made a number of commits directly to your `master` branch by mistake, you will need to use a procedure to move them to a branch, or you will be unable to work with you remote origin. @@ -187,6 +187,8 @@ git push origin BranchNewSection Once you have pushed your branch to the remote repo, you should **inform the editor of it by making a _merge request_**. This can be easily made in the GitLab web, in the _Merge Requests_ area (on the left side bar). Your recently pushed branch would be there to be selected for your new merge request. +When creating the merge request, **select _Delete source branch when merge request accepted_ option** so that the source branch is deleted when the merge request is merged. + ### Step 4: Result of the review Following your _merge request_, the editor will revise the changes suggested in your branch and decide whether they should be merged or receive comments from the editor. @@ -200,22 +202,66 @@ git checkout master git pull origin master ``` -## TODO: Guide for editors +## Guide for editors + +### Initial setup of the repository + +#### If you start from a local folder and the repo in ETSI's Gitlab is still empty (initial load of info) + +```bash +cd existing_folder +git init +git remote add origin git@osm.etsi.org:osm_doc/test.git +git add . +git commit -m "Initial commit" +git push -u origin master +``` + +#### If the repository in ETSI's Gitlab already exists and may have valuable information + +Check the corresponding sections of the [Guide for contributors](#step-0-setup-the-repository-in-your-local-environment-for-the-first-time) + +### Edition and processing of open merge requests + +Tne editor can view all the pending merge requests within a project by navigating to **Project > Merge Requests** in the Gitlab web of the project for the document. That merge request would be associated to a new branch, which can be also be checked navigating to **Repository > Branches**. -### Step 0: Setup of the repository and initial contribution +For instance, for a group of committers (Group) called `osm-doc` and a project called `documentation-how-to`: -#### If you start from an empty local folder and the repo in ETSI's Gitlab is still empty **(RECOMMENDED)** +- The list of pending Merge Requests would be at `https://osm.etsi.org/gitlab/osm-doc/documentation-how-to/merge_requests` +- The list of branches would be available at `https://osm.etsi.org/gitlab/osm-doc/documentation-how-to/branches` -#### If you have the content in a local folder and the repo in ETSI's Gitlab is still empty (initial load of info) +TODO: Include some screenshots -If it was not under Git control yet, initialize it: +TODO: First online review and, if needs to be rejected, include comments where applicable + +If the contribution it is acceptable for a merge, the merge process can be conducted either in the website (particularly if it is a simple review) or in the editor's local repo. + +The following steps describe the case of the local repo. + +TODO: Update your local repository to retrieve the branch of the _merge request_ + +TODO: Launch a merge + +TODO: Once solved, mark the merge request as approved in the website and remove the branch. If applicable, update the local repository with a `git pull` + +If the merge does not imply conflicts with `master` branch, it will be smoothly solved by Git (as a _fast forward_ or a _recursive_ merge) and properly integrated in `master`. + +However, sometimes there might be colliding text lines between `master` and the contribution in the branch. In those cases, Git will request some manual intervention from the editor to proceed to a more careful merge. + +#### How to resolve merge conflicts + +When there is a _merge conflict_, Git leaves a special edited version of the conflicting file in the local working directory, which will include both conflicting proposals for a given line, one after the other, leaving the final result at editor's discretion. + +Once solved by the editor (manually), the file can be added, committed and pushed again as normal: ```bash -git init +git add conflictingfile.md +git commit +git push -u origin master ``` -Add the URL of the remote repository: +However, if eventually you were doubtful of your attempt to address the conflicts with the editor, it is always possible to revert the merge process (so it can be restarted later again) with: ```bash -git remote add origin git@osm.etsi.org:osm-doc/test.git +git merge --abort ```