From b23fcdf571359fe2b943b731cf8e4cd4cc7b81f3 Mon Sep 17 00:00:00 2001 From: Darragh Bailey Date: Mon, 14 Nov 2016 18:09:01 +0000 Subject: [PATCH] Clean up basic inaccuracies in documentation Correct various mistakes in documentation and remove unnecessary paragraphs. Change-Id: Ia16095c88e7873bd815791a32ae3e93ed4ac6d54 --- README.rst | 16 +++---- doc/source/workflows.rst | 96 +++++++++++++++++++--------------------- 2 files changed, 53 insertions(+), 59 deletions(-) diff --git a/README.rst b/README.rst index 17c11f0..025bef4 100644 --- a/README.rst +++ b/README.rst @@ -141,7 +141,7 @@ commands. any part of commit message (e.g., other headers). -Current git-upstream version supports the following features +Git-upstream currently supports the following features - **Single upstream branch import** @@ -164,11 +164,11 @@ fully re-reviewed or merged into master and pushed. - **Detailed logging** git-upstream can output to both console and log file simultaneously. -Multiple levels and these are managed separately for log file and -console output. This means jobs run by Jenkins can save a detailed log -file separately as an artefact while printing status information to the -console if those running the jobs don’t wish to have the console spammed -with the details. +Multiple log levels are supported, and these are managed separately for +log file and console output. This means jobs run by Jenkins can save a +detailed log file separately as an artefact while printing status +information to the console if those running the jobs don’t wish to have +the console spammed with the details. - **Dropping of changes that appear upstream** @@ -179,9 +179,9 @@ that have appeared on the upstream branch since the last import point. Once the list of changes to be re-applied has been determined (and those to be dropped have been pruned), the tool can open an editor (controlled -by your git editor settings) for users to review those changes to be +by a user's git editor settings) for users to review those changes to be made and allow them to perform further operations such as re-ordering, -dropping of obsolete changes, squashing. +dropping of obsolete changes, and squashing. - **Dropping local changes** diff --git a/doc/source/workflows.rst b/doc/source/workflows.rst index 40f3e17..3d0584a 100644 --- a/doc/source/workflows.rst +++ b/doc/source/workflows.rst @@ -1,16 +1,11 @@ Workflows ========= -.. note:: this guide assumes that you are using a branch named *master* +.. note:: This guide assumes that you are using a branch named *master* to maintain your new features or bug fixes that sit on top of the upstream code of some project (probably somewhat related to OpenStack). - It is also assumed you are tracking releases, which is only one of - the possible approaches to upstream tracking. Another approach would - be tracking the master tip of a project. Of course even other - strategies are possible. - Importing from upstream: using git-upstream ------------------------------------------- @@ -185,8 +180,8 @@ Environment File Plugin (finally!). Reviewed-by: Clark Boylan Tested-by: Jenkins -Import those changes simply cherry-picking the two commits. Don’t forget -to push (review!) your changes. +Import those changes by simply cherry-picking the two commits. Don’t +forget to push (review!) your changes. .. code:: bash @@ -197,7 +192,7 @@ to push (review!) your changes. Importing new versions from upstream ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Days passes and finally a new releases comes out. +Time passes and finally a new releases comes out. .. code:: bash @@ -207,23 +202,17 @@ Days passes and finally a new releases comes out. xargs git push --tags origin A lot of work has been done upstream and we need to rebase our master -onto the upstream master branch. In this process we must skip all the -commits we already cherry-picked some days ago, of course. - -.. note:: the rebasing for this example is trivial but it is just to - break the ice. Later in this guide we will address rebasing - conflicts that can occur in the real world. - -Create a new local branch with the new release tag as a starting point - -.. code:: bash - - git branch import/0.6.0 0.6.0 +onto the upstream master branch. In this process we want to skip all +the commits cherry-picked some days ago, where they have merged +upstream. Running git-upstream ~~~~~~~~~~~~~~~~~~~~ -Finally, it is time to run git-upstream! Before doing so make sure the +Identify the commit/tag/branch to import from, in this example we'll use +``0.6.0`` as a tag for a recent release we want to import. + +Now, it is time to run git-upstream! Before doing so make sure the current branch is master .. code:: bash @@ -232,7 +221,7 @@ current branch is master .. code:: bash - git-upstream import import/0.6.0 + git-upstream import 0.6.0 Searching for previous import Starting import of upstream Successfully created import branch @@ -249,9 +238,9 @@ current branch is master What has just happened? git-upstream has created a new branch named ``import/0.6.0-base`` which -tip is set to the commit pointed by the release tag ``0.6.0``, and has -rebased all changes present in our local master which were not already -present in the upstream new release (``import/0.6.0-base``) onto +tip is branched from the release tag ``0.6.0``, and has rebased all +changes present in our local master which were not already present in +the upstream new release (``import/0.6.0-base``) onto ``import/0.6.0-base``. You can see that running the following command @@ -263,10 +252,11 @@ You can see that running the following command For this trivial example, the only commit not present in the upstream release was about the customisation of the .gitreview file. -The default strategy git-upstream uses to find duplicate entries is the -comparison of Change-id entries in commit messages. Of course, it’s not -possible to compare directly the SHA1 for a commit because the -cherry-picking changes the information used for SHA1 calculation +The default strategy git-upstream uses to find duplicate entries is +exactly the same as ``git-rebase``, which works for both cherry-picked +and rebased commits. Additionally it also looks at Change-Id entries +in commit messages where found, as these help identify patches that were +changed before being accepted upstream when using Gerrit for reviews. .. note:: A git commit SHA1 is generated from the following information: @@ -276,12 +266,27 @@ cherry-picking changes the information used for SHA1 calculation - tree SHA1 (hierarchy of directories and files within the commit) - list of the SHA1's of the parent commits + This prevents usage of the commit SHA1 as a method of finding + duplicates. Git-upstream makes uses of git's internal patch-id to + find identical changes. Git-patch-id generates an id based on the + the changes made to the tree, which can be used to identify + different commits with the exact same code changes as a duplicate + commit. + + Git-upstream's makes use of Change-Id's from Gerrit to identify + additional commits that have the same intention, but are different + due to changes made at the request of the upstream. The final patch + being slight different cannot be matched using git-patch-id as it + will return a different output to the current carried patch. + -------- The local branch ``import/0.6.0`` now contains our local changes rebased onto the new upstream release. git-upstream has also merged this branch -with the local master branch (with "ours" strategy) to allow the normal -workflow (committing/merging to master for review). +with the local master branch (with a custom merge strategy equivalent to +the inverse of 'ours', which is not to be confused with the 'ours' option +to the recursive merge strategy) to allow the normal workflow +(committing/merging to master for review). .. note:: The "final" merging step is not mandatory. Of course you can keep a separate branch for each new import. On one hand this @@ -362,28 +367,17 @@ Depending on the type of conflict, you will could: upstream code. You can later resume rebasing process issuing ``git rebase --continue`` -Currently git-upstream can't resume the rebasing process. So, if needed, -the final "merging" steps have to be performed manually: +By default git-upstream should automatically be re-called as the final step +of the rebasing process. Unless however you have used the option +``--no-merge`` as an argument to the import command. + +In such cases, where you wish to subsequently finish, the ``import`` +subcommand provides a ``--finish`` option to assist: .. code:: bash - git merge -s ours --no-commit - -Replacing tree contents with those from the import branch - -.. code:: bash - - git read-tree -u --reset - -Committing merge commit - -.. code:: bash - - git commit --no-edit - -.. note:: git-upstream performs exactly those steps in order to replace - the content of ``master`` branch with the import branch preserving the - history. + git checkout master + git upstream import --finish --import-branch import/0.5.0 0.5.0 Integration with Gerrit -----------------------