Add branching change info to README

README.adoc

@@ -7,34 +7,81 @@ This is the source for the official SUSE Cloud Application Platform (CAP) Docume
 Released versions of the documentation will be published at
 https://documentation.suse.com/ once available.
 
+== Branches
+
+***On Jan 29, 2020, we changed to a new branching model. We have switched the default branch from `develop` to `master`.***
+
+* *Use the master branch* as the basis of your commits/of new feature branches.
+
+* The *develop branch has been deleted* on the server. Do not to push to the `develop` branch.
+  Your changes may go lost in the medium term and never make it to the proper branch.
+
+=== How to Update Your Local Repository
+
+If you *created* a local clone or GitHub fork of this repo *before Jan 29, 2020, do the following*:
+
+1. Make sure that your `master` and `develop` branches do not contain any important changes.
+  If there are changes on either branch, export them using `git format-patch` or put them on a
+  different branch.
+
+1. Go to the master branch: `git checkout master`
+.
+
+1. To pull the latest changes from the remote repository and to delete references to branches
+   that do not exist anymore on the server, run the following command: `git pull --prune`
+.
+
+1. Delete your local develop branch: `git branch -D develop`.
+
+1. To check for stale local branches, run: `git branch -v`.
+   For any branches marked as `[gone]`, check if you still need them. If not, delete them:
+   `git branch -D BRANCHNAME`
+
+
+.Overview of important branches
+[options="header"]
+|================================================
+| Name            | Purpose
+| `master`        | doc development (latest development version)
+| `maintenance/*` | maintenance for released versions
+|================================================
+
 == Contributing
 
-If you would like to contribute, pull requests are welcome. Always create your working branch from the `develop` branch. You are also welcome to open a GitHub Issue and write your contribution in plain text, and we will take care of the rest.
+Thank you for contributing to this repo. When creating a pull request, please follow the guidelines below:
+
+. If you want to contribute to the most recent release, create your pull request against the `master` branch (not `develop`). The `master` branch is protected.
+
+. If you want to contribute to a previous release, please create your pull request against the respective `maintenance/*` branch. These branches are also protected.
 
-Contributors with direct access to the repository are encouraged to use the
-git-flow-avh workflow (package `git-flow-avh`). However, this is not a must.
-For help on style and structure, refer to the https://doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/[Documentation Styleguide] 
+. Make sure all validation (Travis CI) checks are passed.
 
+. For your pull request to be reviewed, please tag the relevant subject matter expert(s) from the development team (if applicable) and members of the documentation team.
+
+. Implement the required changes. If you have any questions, ping a documentation team member in #susedoc on RocketChat.
+
+. For help on style and structure, refer to the https://doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/[Documentation Styleguide].
 
-.*No commits to master*
-NOTE: Please do not make any commits to the `master` branch. `master` is
-reserved for releases only. Always commit to `develop`.
 
 == Editing DocBook
 
-If you are interested in learning the official Doc Team way of writing
-the official SUSE product documentation, follow these suggestions. 
-Our source files are written using DocBook XML and built with DAPS
-using custom stylesheets.
+To contribute to the documentation, you need to write DocBook.
 
 * You can learn about DocBook syntax at http://docbook.org/tdg5/en/html .
 * SUSE documents are generally built with DAPS (package `daps`) and the
-  SUSE XSL Stylesheets (package `suse-xsl-stylesheets`). It's available as a
-  SUSE rpm package from the the SUSE repository http://download.opensuse.org/repositories/Documentation:/Tools/[Documentation:Tools] or
-  directly from https://github.com/openSUSE/suse-xsl/[Github].
+  SUSE XSL Stylesheets (package `suse-xsl-stylesheets`).
+
+*  Install the documentation environment with the following command:
++
+[source]
+----
+sudo /sbin/OneClickInstallUI https://gitlab.nue.suse.com/susedoc/doc-ymp/raw/master/Documentation.ymp
+----
+
 * Basic daps usage:
 ** `$ daps -d DC-<YOUR_BOOK> validate`: Make sure what you have written is
     well-formed XML and valid DocBook 5
 ** `$ daps -d DC-<YOUR_BOOK> pdf`: Build a PDF document
 ** `$ daps -d DC-<YOUR_BOOK> html`: Build multi-page HTML document
+** `$ daps -d DC-<YOUR_BOOK> optipng`: Always optimize new PNG images
 ** Learn more at https://opensuse.github.io/daps