Add documentation for retiring a project from RDO

Also updated following:-
- remove references for stein-py3-uc tag which is no longer valid
- Add mapping for RDO Trunk Repos and Tag in rdoinfo
- Add info for master-head DLRN builder

source/documentation/add-packages.html.md

@@ -63,8 +63,8 @@ the `rdo-review +` flag is set in the Bugzilla bug, the initial spec review will
 in Gerrit.
 
 5. Finally, send a new review to rdoinfo project to remove the `under-review` tag from `tags/under-review.yml` file
-and add tags for which package needs to be build, For current release Stein, 3 files need to be updated(`tags/stein.yml`,
-`tags/stein-uc.yml`, `tags/stein-py3-uc.yml`) ([example](https://review.rdoproject.org/r/#/c/18757/)).
+and add tags for which package needs to be build, For current release Train, 2 files need to be updated(`tags/train.yml`,
+`tags/train-uc.yml`) ([example](https://review.rdoproject.org/r/#/c/18757/)).
 This change can be sent before merging review in step 3 if a `Depends-On: <gerrit-change-id step 3>`
 is added, but the review will only be approved once the `rdo-review +` flag has been
 set in the Bugzilla.

source/documentation/intro-packaging.html.md

@@ -218,7 +218,7 @@ The files under `tags` and `buildsys-tags` directories are named based on names
 this is defined as follows:-
 
 - release: is a the OpenStack release name, as pike, queens, rocky or stein.
-- tag: tag for which project is build, like queens, rocky, stein, stein-uc, stein-py3-uc, etc.
+- tag: tag for which project is build, like queens, rocky, stein, train, train-uc, etc.
 - phase:
   - `candidate` phase is assigned to packages to be rebuilt in
   CBS but not pushed to any RDO repository.

source/documentation/rdo-packaging.html.md

@@ -49,6 +49,7 @@ title: RDO Package Maintainer Guide
 ## Package Maintainer common tasks
 
 * [Adding new packages to RDO](/documentation/add-packages/)
+* [Retiring a package in RDO](/documentation/retire-packages/)
 * [Adding a new requirement](/documentation/requirements/#adding-a-new-requirement-to-rdo)
 * [Updating a requirement](/documentation/requirements/#updating-a-requirement-in-rdo-cloudsig-repositories)
 * [Fixing a FTBFS (failed to build from source)](https://blogs.rdoproject.org/7903/how-to-fix-a-ftbfs-using-dlrn)

source/documentation/retire-packages.html.md

@@ -0,0 +1,59 @@
+---
+author: ykarel
+title: Retiring a package
+---
+
+# Retiring a package from RDO
+
+1. toc
+{:toc}
+
+### What does retiring a package means
+
+- The package will not be build and published to RDO Trunk repo
+- The package will not be build in CBS and published to next CloudSIG repo
+
+
+**NOTE:** The package can be retired only from the current development release.
+
+### How to remove an OpenStack package from RDO Trunk
+
+Package for a project can exist across different releases. So retiring it in RDO needs to go via stages.
+
+To remove a package, following steps are required:-
+
+**Stage 1:-** Project Source is retired/deleted upstream, but it's package still need to be maintained because it's required by other projects
+
+- Send a review to `rdoinfo` like [Example review](https://review.rdoproject.org/r/#/c/20387/) to pin(add source-branch: `<good commit>`) the project against the tag or commit, so package get's build from pinned commit rather than latest commit(deleted source code).
+
+    ```
+    # Need to add source-branch like below
+    - project: oslo-sphinx
+      tags:
+        train-uc:
+          source-branch: f92583cfc34292ec1441368f984c9692346946c4
+     ```
+
+- Send a review to `config` project like [Example review](https://review.rdoproject.org/r/#/c/20415/) to run DLRN-pinned jobs(legacy-DLRN-rpmbuild-pinned, legacy-DLRN-rpmbuild-fedora-pinned) so package get's build from pinned commit rather than from latest, This is required so that spec changes can be done like https://review.rdoproject.org/r/#/c/20383/.
+
+**Stage 2:-** Package is no longer needed by other projects:-
+
+- Send a review to [rdoinfo project in review.rdoproject.org](https://review.rdoproject.org/r/#/q/project:rdoinfo).
+In this change you need to delete the tag for the project for which package is not needed to built.
+
+Once the change is merged in rdoinfo, package will no longer exist in RDO trunk repo, but it will still be built for previous releases(for which
+tag is defined in `rdoinfo`):-
+[RDO Trunk repos](http://trunk.rdoproject.org/centos7-master/report.html).
+
+**Stage 3:-** Package is no longer needed as it's not built for any release, no spec changes needed in future, so project needs to be deleted from review.rdoproject.org.
+
+- Send a review to `config` project to remove all jobs against the project and just add noop job like below so patches can be merged in the projects as Zuul +1 is required:
+
+    ```
+    # following need to be added to the project's job config to run noop jobs:-
+    - templates:
+        - noop
+    ```
+
+- Delete the project spec files and add dead.package file mentioning the reason of removal
+- Remove project completely(project-config, resource,gerritbot etc) from zuul config

source/what/trunk-repos.html.md

@@ -4,12 +4,21 @@ title: Workflow - RDO Trunk repos
 
 # Workflow: RDO Trunk repos
 
-RDO Trunk repositories are built using the most recent commit from each of the OpenStack projects. We host the RDO Trunk repositories at [https://trunk.rdoproject.org/](https://trunk.rdoproject.org/). On that server, you will find several repositories:
+RDO Trunk repositories are built using the most recent commit(or from the pin to a commit/tag/branch if ``source-branch`` is set for a release in [rdoinfo](https://github.com/redhat-openstack/rdoinfo/tree/master/tags)) from each of the OpenStack projects defined for a release. We host the RDO Trunk repositories at [https://trunk.rdoproject.org/](https://trunk.rdoproject.org/). On that server, you will find several repositories:
 
-- CentOS 7 master
-- CentOS 7 master, using versions from upper-constraints
-- CentOS 7 stable releases for the currently supported versions
-- Fedora Rawhide master
+- [CentOS 7 master, with everything from master](https://trunk.rdoproject.org/centos7-master-head/consistent/)
+- [CentOS 7 master, using versions from upper-constraints](https://trunk.rdoproject.org/centos7-master/consistent/)
+- [CentOS 7 stable releases for the currently supported versions](https://trunk.rdoproject.org)
+- [Fedora 28 master](https://trunk.rdoproject.org/fedora28-master/consistent/)
+
+[CentOS 7 master, with everything from master](https://trunk.rdoproject.org/centos7-master-head/consistent/) repo is not tested by any CI job, this repo is created as a result of building recent commits to get packaging issues early for the projects which are pinned in rdoinfo. 
+
+These repos contains packages build for each OpenStack project defined for a particular release in ``rdoinfo``. This mapping of repo and release is as follows:-
+
+- [CentOS 7 master, with everything from master] with current release rdoinfo tag i.e [train](https://github.com/redhat-openstack/rdoinfo/blob/master/tags/train.yml) 
+- [CentOS 7 master, using versions from upper-constraints] with current release rdoinfo tag i.e [train-uc](https://github.com/redhat-openstack/rdoinfo/blob/master/tags/train-uc.yml)
+- [CentOS 7 stable releases for the currently supported versions] with stable release rdoinfo tag other than current release [train, train-uc](https://github.com/redhat-openstack/rdoinfo/blob/master/tags/)
+- [Fedora 28 master] with current release rdoinfo tag i.e [train-uc](https://github.com/redhat-openstack/rdoinfo/blob/master/tags/train-uc.yml)
 
 ## The upper-constraints based repositories
 
@@ -19,7 +28,7 @@ Why is this file important? It defines an upper cap for every gate job, meaning
 
 This is also important when packaging, because we want our generated repositories to be usable by upstream CIs, so we need to provide a set of packages that matches the versions available in the ``upper-constraints.txt`` file. Thus, we have two separate repositories for master:
 
-- [CentOS 7 master, using versions from upper-constraints](https://trunk.rdoproject.org/centos7), where all libraries and clients are built from the latest versions in ``upper-constraints.txt``, and every other project is built from the master branch.
+- [CentOS 7 master, using versions from upper-constraints](https://trunk.rdoproject.org/centos7-master), where all libraries and clients are built from the latest versions in ``upper-constraints.txt``, and every other project is built from the master branch.
 - [CentOS 7 master, with everything from master](https://trunk.rdoproject.org/centos7-master-head), where every project is built from the current master. This is used as a _canary in a coal mine_, as an early warning method for upcoming issues, so they can be fixed before they reach the upstream gates.
 
 For stable releases, we also follow the upper-constraints approach.