DNNCommunity
RFC: Merging Changes Across DNN Versions
The question is how do we handle a situation where the current version of the docs is for DNN 10. We've already released and have branches for DNN 8 and DNN 9. A change is made to a topic that applies to DNN 8-10. How do we handle getting that change in the DNN 8 branch merged into the DNN 9 and DNN 10 branches.
I think our best option is to use cherry picking. This a git command that allows us to take a specific commit in one branch and copy it into another branch. Its use is discouraged in development scenarios primarily because you are creating a copy of the changes in the commit and making a new commit on the new branch with those changes. In a development scenario, this isn't idea. because you lose the history of the original commit. However, this isn't a development scenario. We don't need to track changes to the content across time over all branches.
In order to do this, we should adopt a policy of 1 commit per file, unless the same change is made across multiple topics. Since cherry picking works with commits, the more granular we can make those commits, the easier it will be to get just the content we want. Plus, you can cherry pick multiple commits in one command.
How Cherry Picking Works
Let's say we have a master branch with the current DNN version (say, DNN10) and have a branch for DNN8 and DNN9. We'll call these branches: dnn10 dnn9 dnn8 and master (which contains the current release of the docs, regardless of DNN version). Let's also assume that changes were made to a topic in the dnn8 branch that should also apply to dnn9 and dnn10.
Step One: Get the Hash of the Source Commit
The first thing we need to do is identify the specific commit(s) we want to merge.
git checkout dnn8
git log --oneline
5dfe882 Changed File Title to Creating Users
12dc37f Added Creating Portal topic
For this example, we'll use 5dfe882
Step Two: Switch to the Target Branch
git checkout dnn9
Step Three: Do the Cherry Pick
git cherry-pick 5dfe882
You can pull in multiple commits by simply adding them to the command:
git cherry-pick 5dfe992 12dc37f
Step Four: Push your Changes
git push
I found this note in the React docs (https://reactjs.org/docs/getting-started.html#versioned-documentation)
It reflects how they handle new versions....
This documentation always reflects the latest stable version of React. Since React 16, you can find older versions of the documentation on a separate page. Note that documentation for past versions is snapshotted at the time of the release, and isn’t being continuously updated.
Perhaps we don't worry too much about older versions? Food for thought.
I actually think for a good documentation system it is essential to make a difference between the different versions. If some user want's to look up something while he is working in version 8.xx.xx it is good to know if something applies to his situation or not.
Thanks for your input @trouble2. We do intend to have a mechanism for switching or otherwise filtering based on DNN version. One purpose of this RFC is to figure out we will handle the changes between versions while minimizing the amount of redundancy.
As an example, if we have a docs for v.9, v.10, and v.11 and someone discovers an inaccuracy in v.11 that is also applicable to v.9 and v.10, what is the best approach to keeping those older versions updated without having to find and fix each version. It may not be possible. We may have to suck it up and ensure the older versions are also updated. But it is worth exploring at this stage in the docs development to see how we could minimize the work involved.