Doc release update process

The ACRN release process starts when the code is frozen on the candidate release branch, such as release_2.7. Documentation changes continue on the master branch while developers are validating and testing the release candidate. Once the release candidate branch is declared ready, we need to propagate all the documentation changes that were done on the master branch back into this release candidate branch as well. In the past, doc changes were cherry-picked one-by-one from the master branch to the release candidate branch, but for a while now we simplified this process (and reduced the chance of missing a documentation change) by essentially merging all the documentation changes made on the master branch since the release candidate branch was made. We do this by making a working directory with content from the master branch, checking out the release candidate branch, and then copying that working directory content onto the checked-out release candidate to create a single pull-request with all the changes. The working assumption here is that all the doc changes done on master after the release branch was created are intended for master and the release branch and any doc changes not intended for both won't be merged onto master until after the release is made.

Here's the process:

# create a "master" working directory
rm -rf ~/acrn-master && mkdir ~/acrn-master
cd ~/projectacrn/acrn-hypervisor/doc

# get the latest upstream/master branch content 
git checkout master
git fetch upstream
git merge upstream/master
git push origin master

# clean out doc build artifacts
make clean

# copy all the doc directory to our master working directory
cp -r . ~/acrn-master/doc

# and copy doc material from the misc directory too
cd ../misc
mkdir ~/acrn-master/misc

# the --parents option maintains the directory structure in the destination directory
# Assumption is there are only .rst files of interest, no images in the misc folders
cp --parents *.rst ~/acrn-master/misc
cp --parents */*.rst ~/acrn-master/misc
cp --parents */*/*.rst ~/acrn-master/misc
cp --parents */*/*/*.rst ~/acrn-master/misc
cp --parents */*/*/*/*.rst ~/acrn-master/misc

# until that last copy fails. Then get the schema files that contain configuration option documentation
cp --parents config_tools/schema/*.xsd ~/acrn-master/misc

cd ..

# get the release candidate doc contents and make a branch for updating
git checkout upstream/release_2.7
git checkout -b update-docs-2.7

# and copy all the master working directory doc contents over the release candidate contents
cp -r ~/acrn-master/* .

# check for files that were deleted in the master branch but are still on the release_2.7 branch
diff -rq doc ~/acrn-master/doc | grep "Only in doc"
# or use this to actually delete them:     
rm -rf `diff -rq doc ~/acrn-master/doc | tr -d "\:" | grep "Only in doc" | awk '{print $3 "/" $4}'`

# something similar for the misc content, but we only want to look at .rst and .xsd files
diff -rq misc ~/acrn-master/misc | egrep "(\.rst|\.xsd)" | grep "Only in misc"

# do a "make html" here to verify CI doc build will work...
# we can publish these as the 2.7 release docs if all's well
cd doc
make clean
make DOC_TAG=release RELEASE=2.7 html 
make DOC_TAG=release RELEASE=2.7 publish

# add changed staged files, commit, and do the PR
cd ..
git add .
git status 
# verify all staged files are added (from the /doc and /misc directories)

git commit -s
# in the commit message add "Tracked-On: #5692" to allow the .xsd file changes to get through CI checks
# otherwise we'll get a CI error because there are non-doc changes

git push origin update-docs-2.7

From here, head over to https://github.com/projectacrn/acrn-hypervisor and create a PR, changing the base to be the release_2.7 branch (not master). You should see only the changed documents listed as changed files, and there should be no merge conflicts. It's a good idea to walk through all the changes (or at least the changed files) to verify that no unintended doc changes snuck in. You might find a doc change on master got included that wasn't intended for the release branch.

Submit the PR and wait for the CI system to pass before merging.

While that's going, we can head back to the master branch, and make the changes to incorporate the 2.7 release docs into the latest doc version status by editing the conf.py file, as documented in Document Versioning.

cd ~/projectacrn/acrn-hypervisor/doc

git checkout master
git checkout -b add-v2.7-menu

# edit the conf.py to add the v2.7 release docs to the menu choice after /latest/

git add .
git commit -s
git push origin add-v2.7-menu

# then build and publish the /latest documents (if the edit didn't cause an error)
make html
make publish

# head over to github and submit the PR to update the conf.py

And your done merging, building, and publishing the v2.7 documents, and rebuilding and publishing /latest to include a link to the v2.7 docs in the version menu.