Notes
It’s important that you execute a particular kind of merge. I.e., if you run a regular merge, all of your original individual commits will be transformed into one large fast-forward commit. A fast-forward only updates the HEAD pointer; it doesn’t create a commit object.
Note: You can’t just push the new commits into your mainline because the branch names differ. This can happen if another writer spawned and working branch, completed their work, and then merged their new content into your mainline (thus, advancing HEAD by one commit). Alternately, if you currently have another working branch with unfinished work. In both cases, all you have to do is execute git pull before you push, so it’s in synch with your mainline.
To can preserve the history of your revisions, you must specifying command line options:
- Force “no fast forward” (–no-ff),
- Show a difference statistic at the end of the merge (–stat),
- Specify the use of the recursive strategy for the merge (-s recursive),
- Specify that change priority be given to the new content (from in the source branch) (-X theirs),
- Add a comment for the commit (-m).
Example
Merging the new content from /v1.4x_doc_update, into your local feature/api_doc branch.
git merge -s recursive -X theirs v1.43_doc_updates
Note: In Git terminology, the original content belongs to yours, and the new content belongs to theirs.
To avoid aborting an auto-merge when it hits a conflict (in particular, one that results from the insertion of a new item into the middle of a reference table), be sure to use the Recursive Merge Strategy, and use it with the theirs option. Why? Because this particular option forces conflicting content to be auto-resolved cleanly by favoring the new content.
Example
git merge -s recursive -X theirs v1.43_doc_updates
For more information, see: https://www.kernel.org/pub/software/scm/git/docs/git-merge.html.
1. Rebuild the docs
In Eclipse, click Run > Run History > 1 Rebuild HTML Docs.
2. Archive this doc build
Copy this version of the docs
Use this time-saving trick: Double-click the link below and Windows Explorer automatically opens, displaying the directory of the current build. Click anywhere in the contents pane, Select All (Ctrl+A), and copy everything to the Clipboard (Ctrl+C).
C:\Users\Chris\src\python_rest_api\doc\user\v1\build\html
Within this directory, create a new directory to hold this doc snapshot
Give it a name that indicates what made this doc version special. E.g., KeyPress.
Paste
Open the new directory, and paste the content of the Clipboard into it.
3. Make sure the working directory is clean
That is, make sure that you have no unstaged changes. In Eclipse, with the project folder selected in the PyDev Package Explorer, open the Git Staging tab, and click Refresh. If you have unstaged changes, stage them, and then commit them; and then go back and start again (from Step 1. Rebuild the docs).
4. Switch to the feature/api_doc branch
In Eclipse, right-click the project folder in the PyDev Package Explorer tab, and then click Team > Switch to > feature/api_doc.
Or from the git bash
Open a Git BASH, navigate to the current project working folder, and execute the following command:
$ git checkout feature/api_doc
5. Make sure your local branch is in sync (is up to date) with the remote repository
Update your local repository. This is a precautionary measure, in case the remote tracking branch has any commits that you don’t have locally. You didn’t do this once, and it caused you problems (which you easily solved by simply pulling – but it took you a while to figure out what the nature of the problems was).
Note: You must have a VPN connection to 3rdParty.
In Eclipse,
Right-click the project folder in the PyDev Package Explorer tab, and then click Team > Fetch from Upstream.
Or from the git bash
git fetch
6. Create the merge command line
Copy the example git command line below, to a new blank file in EditPad Pro, and revise the <comment/> and <branch_name/>, and then copy the line to the clip board.
git merge --stat --no-ff -m "<comment/>" -s recursive -X theirs <branch_name/>
E.g., (copy & paste from EditPad Pro)
git merge --stat --no-ff -m "Added HTTP status code 429 Too Many Requests" -s recursive -X theirs v1.43_updates
7. Execute the merge
At this point in time, I don’t know how to execute this command in Eclipse.
From the git bash
Click anywhere inside the Git command window, and then dump the contents of the clipboard onto the command line (Trick: right-click).
Note
The merge might have conflicts. If so, then run git mergetool.
Example
git merge --stat --no-ff -m "Added HTTP status code 429 Too Many Requests" -s recursive -X theirs v1.43_updates
8. How to resolve merge conflicts if any
Prerequesite: You’ve registered Beyond Compare 4 as the merge tool in the Git environment.
- Run the merge
From the Git BASH, execute the comnmand: git mergetool, and then press Return. Beyond Compare launches, and displays the original version of the file in the left pane, and the revised version in the right pane. The lines that conflict are highlighted.
- Accept revisions into the original file
In the bottom pane, accept each one in succession, and/or edit the content to your liking.
- When you’re done with that file, click File > Exit
This kicks you back to the Git BASH.
- If there’s another file conflict, just wrince & repeat
Press Return, and step through the conflicts in this file.
Note: At this point, the merge isn’t actually done, despite the fact that you’ve resolved all of the conflicts.
- Conclude the merge
Commit the merge object, and include an informative message.
git commit -m "Merged new content for R1.42 (Verify Registration)."
9. Push the new content upstream
That is, update remote refs along with the associated tree objects from your local feature/api_doc to origin feature/api_doc.
- From the git bash, enter the following command:
git push --tags
- Copy that last line (the one immediately above) so you can use it in the broadcast e-mail.
What to do when there isn’t yet, an upstream branch
You spell it out for Git. I.e., “Create a branch called ‘feature/doc_update’ in the origin repository”.
git push origin feature/doc_update
10. Check the local branch status
Just to make sure the push worked properly.
git status
11. Create a new branch for the next release
You should still have the feature/api_doc checked out, and it should now be up to date with respact to your latest bits. From here, spawn a new branch for your work for the next drop. From the Git BASH, enter the command:
git branch --track -l v1.4x_doc_updates
12. Send the broadcast email
Right after you push your doc updates to the origin repository, send a broadcast e-mail to the team summarizing the changes, asking for (making) a Pull Request, and CC PM (the PM distribution list).
Note: Set the Importance level to High.
In the body of the message, list the doc work items that went into this doc update. You can get this information quite easily in Eclipse. Simply select the Git Reflog tab. The line items of interest are the ones with “commit:” in the Reflog Messages.
E.g.
To: pm@3rdParty.com Importance: High
Subject: Pull Request: REST API Docs v1.51
I pushed a documentation update (To git@git.c11.3rdParty.com:python_rest_api.git 26d53cf..62ed6c1 feature/api_doc -> feature/api_docs ).
This update includes
- TD-41 Fixed a broken link. “State Abbreviation Code” now links to http://pe.usps.com/text/pub28/28apb.htm.
- TD-44 Changed Required to Optional, for the ‘ucid’ request parameter.
- TD-45 Changed the default value for number of verification code digits that 3rdParty automatically generates by default from six, to five.
- TD-48 Corrected two spelling mistakes.
- TD-49 Corrected a spelling mistake.
-
- TD-57 Added two new error codes:
-
- -40008 [Product method] exceeded transaction hard cap; Request denied.
- -60001 PhoneID Contact data not found).
Would you please pull from feature/api_docs, then rebuild the REST API doc set, and then publish it?
If this content update involved TechDoc bugs (Issues), then resolve them as fixed, and then add an appropriate comment
I incorporated this content update in v 1.51 of the REST API docs.
13. Increment the version number
Checkout the new branch. Open the file: doc/user/v1/source/conf.py. Rebuild the docs. Now the current doc build shows the upcoming release number.
14. Put the latest doc set up on Gullinx
Create a new directory. Copy the contents of C:\Users\Chris\src\python_rest_api\doc\user\v1\buildhtml.