From b36ac75d0aaa642805ca18ff0cfc9ec456211ea9 Mon Sep 17 00:00:00 2001 From: ramonsalguer <javier.ramon@telefonica.com> Date: Thu, 21 Mar 2019 19:28:14 +0100 Subject: [PATCH] - Added "Recommendations for editors" - Fixed error in merge command (!) - Minor typos fixed --- ...low for documentation production in OSM.md | 68 +++++++++++++++++-- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/Workflow for documentation production in OSM.md b/Workflow for documentation production in OSM.md index dfaee63..c897af2 100644 --- a/Workflow for documentation production in OSM.md +++ b/Workflow for documentation production in OSM.md @@ -181,7 +181,7 @@ Then you can continue editing until you are ready to share a contribution. When your are ready, you can push your branch to the remote repo: -``` +```bash git push origin BranchNewSection ``` @@ -223,7 +223,7 @@ Check the corresponding sections of the [Guide for contributors](#step-0-setup-t ### 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**. +The 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**. For instance, for a group of committers (Group) called `osm-doc` and a project called `documentation-how-to`: @@ -234,7 +234,7 @@ TODO: Include some screenshots First online review and, if needs to be rejected, include comments where applicable. -If the contribution 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 most generic case of using the local repo. +If the contribution 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 most generic case of using the local repo, although the process would be analogous in the web interface. First, update your local repository to retrieve the branch(es) with the pending _merge request(s)_: @@ -246,7 +246,7 @@ Then, launch the merge operation: ```bash git checkout master -git merge +git merge branchwithcontribution ``` If completed successfully, mark the merge request as approved in the website (**Project > Merge Requests**) and remove the branch if asked (this will clean up the Git tree in GitLab by removing unnecessary temporary branches). @@ -274,3 +274,63 @@ However, if eventually you were doubtful of your attempt to address the conflict ```bash git merge --abort ``` + +### Some recommendations for editors + +#### Markdown style + +In spite of the fact that there is a high convergence around Markdown, some of the most advanced features of the language are not that normalized and may differ slightly among different Markdown flavours. + +In order to minimize potential issues due to ambiguity of format among contributors, in case of doubt, **GitHub Flavored Markdown (GFM)** is highly recommended, given its prevalent popularity and support by most major editors, renderers and viewers. + +#### File structure + +It is highly advisable that the editor provides a base file structure for the document. There are some best practices that apply: + +- Different chapters (i.e. level-1 titles) of the document should be in different markdown files. Likewise, no more than one level-1 title should be placed in the same file. +- Images should be placed in a dedicated folder. The recommendation is using the `./assets` folder. +- Likewise, DOCX templates, auxiliary files, output files, etc. should be placed in dedicated folders +- File and folder names should not contain spaces or any other kind of special characters to maximize portability and minimize rendering or reading errors in various auxiliary tools. To improve readability, an useful convention is using dashes (`-`) to replace spaces. +- The editor should add to the base folder a simple **script to build the document**, so there is no ambiguity to test the results. + +TODO: Include example with all recommendations above, so that it can be easily used as template for new editors. + +### Line length limitation and minimization of conflicts + +A useful peculiarity of Markdown is that any paragraph of the final document can expressed using multiple Markdown lines, since a single carriage return does not create a new paragraph (2 carriage returns are needed to separate paragraphs). This property, among other reasons, is intended to improve readability in some environments. + +Therefore, while the more natural and simplest way to produce and edit markdown files in a Git context can be producing the text as with any other text editor (leading to a single markdown line per paragraph), this singularity of Markdown syntax can be used in editor's favour for files, sections or paragraphs that might be subject to multiple edits and revisions. Thus, in those cases, it would be highly convenient for the editor to split critical paragraphs into lines equal or shorter than maximum length (typically, **79 characters**), so that merge conflicts between contributors are minimized. + +If eventually a whole file were in that situation, `pandoc` can provide a shortcut for automatic conversion to the editor: + +```bash +pandoc busychapter.md -t gfm --columns=79 -o busychapter-wrapped.md +``` + +And then, replace the original file by the new one, so that new contributors can take it as a reference: + +```bash +cp busychapter-wrapped.md busychapter.md +rm busychapter-wrapped.md +git add busychapter.md +git commit -m "File busychapter.md wrapped to 79 characters per line" +git push origin master +``` + +Whenever the editor realises that the document is stable again or if prefers an edition based on lines that equal paragraphs, the previous rewriting can be easily reverted with Pandoc: + +```bash +pandoc busychapter.md -t gfm --wrap=none -o busychapter-nowrap.md +``` + +And then: + +```bash +cp busychapter-nowrap.md busychapter.md +rm busychapter-nowrap.md +git add busychapter.md +git commit -m "File busychapter.md now allows unlimited line lengths" +git push origin master +``` + +**WARNING:** Please make sure that **any of these commits with massive changes in the line wrapping convention is properly announced to contributors**, so that they do not create new contributions based on the former line convention (in branches derived from older commits), or they would be really challenging to handle as merge conflicts (**all the converted lines would be different!**). -- GitLab