Merge "Add a note about creating a release branch"

doc/source/contributor/create-stable-branch.rst

@@ -0,0 +1,142 @@
+Steps to create a stable release branch
+=======================================
+
+Awesome! We've decided as a group to create the next stable branch. Here
+are some steps to remind you on how to do it.
+
+#. Go to `each repo`_ as a core member and create the branch with the
+   SHA you want, usually you will just branch from master.::
+
+     git checkout master
+     git pull
+     git checkout -b stable/<release>
+     git push gerrit stable/<release>
+
+#. Changes for each cookbook and repo, create a bug to tie all the
+   following branch work together
+
+   a. Update ``.gitreview`` to include ``defaultbranch=stable/<release>``
+
+   b. Update ``Berksfile`` to reference ``branch: 'stable/<release>'`` for each branched cookbook
+
+   c. See https://review.opendev.org/729795 for an example
+
+#. Create a review with the above and put it up against the ``stable/<release>`` branch.
+
+#. Get it merged in and you should be good
+
+.. _each repo: https://governance.openstack.org/tc/reference/projects/openstack-chef.html
+
+If you think doing this manually for all the cookbooks is a lot of work,
+these commands might help you automating it (please CHECK the git diff
+before you actually push something):
+
+#. First pull all the cookbooks into one folder and then try to run
+   these commands one by one from the root folder (they are
+   intentionally separated, since they will create some changes that you
+   do not want to push).
+
+   .. code-block:: bash
+
+     for i in -bare-metal -block-storage client -common -compute \
+       -dashboard -dns -identity -image -integration-test -network \
+       -ops-database -ops-messaging -orchestration -telemetry ; do
+       git clone https://opendev.org/openstack/cookbook-openstack${i}
+     done
+
+#. Check your ``sed`` version and make sure you have at least version
+   4.2.1 (if you are on OS X you have to install ``gnu-sed`` via
+   Homebrew since the one installed does work in mysterious ways).
+
+   .. code-block:: bash
+
+     export RELEASE=train
+     for i in $(ls | grep cookbook) ; do
+       cd $i
+       git checkout -b stable/${RELEASE}
+       sed -i "/opendev/a\ \ branch: 'stable\/${RELEASE}'" Berksfile
+       sed -i 's/opendev.*$/&,/' Berksfile
+       echo "defaultbranch=stable/${RELEASE}" >> .gitreview
+       cd ..
+     done
+
+     # The next one is important, since there are changes that are wrong
+     # and should be corrected manually (like adding the branch:
+     # stable/train for a non-openstack cookbook)
+     for i in $(ls | grep cookbook) ; do cd $i; git diff; cd .. ; done | less
+
+     # After you checked all your changes, you can go ahead, commit it and
+     # push it up for review.
+     for i in $(ls | grep cookbook) ; do
+       cd $i
+       git review -s
+       git commit -am "stable/${RELEASE} release patch"
+       git review
+       cd ..
+     done
+
+Steps for a new master branch
+-----------------------------
+
+.. note::
+
+  These steps are also useful when making global changes that are
+  dependent on each other.
+
+Now we have a new master, need to get it in sync with matching base
+OpenStack release.
+
+#. Possible infra changes for changes to the gates we want for this
+   release.
+
+#. Decide on new levels of tools (Chef Workstation, Cookstyle, upstream
+   cookbooks), we have always be trying to move forward with these.
+
+#. Changes for each cookbook and repo:
+
+   a. Update metadata with new major version level
+
+   c. Run ``cookstyle -a`` to fix any style issues. Run Cookstyle again
+      and fix any issues that couldn't be fixed automatically.
+
+   d. Update code with refs to old OpenStack release, i.e. "ocata" ->
+      "pike"  (Common release and yum attributes, ...).
+
+   e. Update all code looking for deprecation's that can now be removed.
+
+   f. Update any package dependencies that have changed for each
+      component.
+
+   g. Update all spec test platforms to targeted levels we want for this
+      release.
+
+It will likely be necessary to disable integration jobs from being
+voting on the ``openstack-chef`` repo in order to allow to merge all
+these changes. If you do so, make sure that you have one patch at the
+end which depends on all others, this one should be passing all
+integration jobs again before you merge anything. See this `topic`_ as
+an example.
+
+.. _topic: https://review.opendev.org/#/q/topic:train-updates+(status:open+OR+status:merged)
+
+You will want to do this in the following order and add ``Depends-On:``
+to each review to it's dependencies. Everything should depend on the
+openstack-chef repo since that's where all of the tests reside and will
+need to be updated. To simplify, you can chain dependencies based on
+their ``metadata.rb`` dependencies. See below on specifics:
+
+#. openstack-chef Repo
+#. Common (depends on openstack-chef)
+#. Client (depends on openstack-chef and Common)
+#. Ops-Messaging (depends on openstack-chef)
+#. Ops-Database (depends on openstack-chef)
+#. Identity (depends on Client, Ops-Messaging and Ops-Database)
+#. Image (depends on Identity)
+#. Block-Storage (depends on Image)
+#. Network (depends on Identity)
+#. Compute (depends on Image and Network)
+#. Dns (depends on Network)
+#. Orchestration (depends on Identity)
+#. Telemetry (depends on Identity)
+#. Dashboard (depends on Identity)
+#. Integration-Test (depends on Image and Dns)

doc/source/contributor/index.rst

@@ -10,3 +10,4 @@ Contributor Guide
    community
    talk-to-us
    ci
+   create-stable-branch