Author: schor Date: Fri Nov 1 21:30:24 2019 New Revision: 1869276 URL: http://svn.apache.org/viewvc?rev=1869276&view=rev Log: no Jira, more git updates
Added: uima/site/trunk/uima-website/xdocs/git-notes.xml Modified: uima/site/trunk/uima-website/docs/git-conventions.html uima/site/trunk/uima-website/docs/git-release-notes.html uima/site/trunk/uima-website/docs/git.html uima/site/trunk/uima-website/xdocs/git-conventions.xml uima/site/trunk/uima-website/xdocs/git-release-notes.xml uima/site/trunk/uima-website/xdocs/git.xml Modified: uima/site/trunk/uima-website/docs/git-conventions.html URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/git-conventions.html?rev=1869276&r1=1869275&r2=1869276&view=diff ============================================================================== --- uima/site/trunk/uima-website/docs/git-conventions.html (original) +++ uima/site/trunk/uima-website/docs/git-conventions.html Fri Nov 1 21:30:24 2019 @@ -240,12 +240,22 @@ but rather, a change must be pulled from a branch via a pull request.</p> <p>Branches for working are typically named using the Jira issue (if there is one) associated with the work, followed by a very-short-description - enough to remind you what that jira number is about. - In addition, the name can be prefixed with the kind of work it is, e.g. <code>feature/</code> or <code>bugfix</code>. + In addition, the name can be prefixed with the kind of work it is, e.g. + <code>feature/</code> or <code>bugfix</code> or <code>refactor</code>. This can be useful in enabling you to more rapidly locate the right branch.</p> <p>After merging into master, the branch is typically deleted.</p> + <h3>Commit messages</h3> + <p>Example: <code>[UIMA-1234] Add missing foo to bar</code></p> + <p>Git has a two-section commit message. The first line should be a one-line id and summary. + Following that is an optional section of multiple lines that are details about the commit.</p> + <p>The first line should start with the jira issue number including UIMA- prefix. Automatic scanners + use this to connect this to the Jira issue. You may put multiple issues if applicable. The issues may + be written with surrounding square brackets, e.g. <code>[UIMA-1234]</code>.</p> + <p>Following that should be short title of the issue, since looking back at it a reader probably won't remember + what the issue was all about. Following that can be a summary of what this particular commit does.</p> <h4>Git merge styles</h4> <p>Different projects may use different merge styles.</p> - <p>See these links for references to common work patterns.</p> + <p>See these links for references to common work patterns. TBD</p> </blockquote> </p> </td></tr> Modified: uima/site/trunk/uima-website/docs/git-release-notes.html URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/git-release-notes.html?rev=1869276&r1=1869275&r2=1869276&view=diff ============================================================================== --- uima/site/trunk/uima-website/docs/git-release-notes.html (original) +++ uima/site/trunk/uima-website/docs/git-release-notes.html Fri Nov 1 21:30:24 2019 @@ -303,8 +303,7 @@ </p> <h2>release:perform</h2> <p>This does a build using the "tag" checkout, and uploads the artifacts to the maven staging repository.</p> - <p>(needs confirmation) the tag is checked out into a new branch, and the new branch is copied into - the branch being built from, in the target/checkout directory. Then the new branch is deleted.</p> + <p>The tag is cloned into the target/checkout directory</p> <p>A build is done from the target/checkout spot, with maven artifacts uploaded to repository.apache.com staging area, just like before.</p> </blockquote> @@ -318,20 +317,27 @@ </td></tr> <tr><td> <blockquote class="sectionBody"> - <p>The idea is to reset the branch being used to build, back to the commit just before the maven release:prepare + <h2>(Optional) Reset the branch to last commit before release:prepare</h2> + <p>If you don't do this, when you do the release:prepare again, it will increment the SNAPSHOT and release numbers, + and you'll need to override those. + </p> + <p>The idea is to reset the branch being used to build, back to the commit just before the maven release:prepare commit, which is identified with the message <code>[maven-release-plugin] prepare for next development iteration</code>.</p> <p>Do this by working in a checkout of the branch being used to build, typing <code>git log</code> and finding the hash for the commit right before the prepare commit.</p> - <p /> - <ul><li><code>git log -5 --oneline</code> shows the last 5 commits. Find the last commit before the maven prepare one.</li> + <p>Don't do this next step unless you know no one has fetched the previously pushed maven release changes. + This is typically true, because only you are working on the release.</p> + <ul><li><code>git log -5 --oneline</code> # shows the last 5 commits. Find the last commit before the maven prepare one.</li> <li><code>git reset --hard hash-of-commit</code> where hash-of-commit is from the log </li> - <li><code>git push origin branch-name</code></li> + <li><code>git push -f origin branch-name # force needed because removing history</code></li> </ul> + <h2>Remove the previously created tag</h2> <p>Next, because the release:prepare created a tag, you need to remove it. Do this:</p> <ul><li><code>git tag</code> to list the tags</li> <li><code>git tag -d name-of-tag</code> to delete, e.g. uimaj-3.1.1. This deletes it locally only.</li> <li><code>git push origin :refs/tags/name-of-tag</code> to remove the tag in the remote.</li> </ul> + <h2>Do any fixes, updates and then rerun the release</h2> </blockquote> </p> </td></tr> Modified: uima/site/trunk/uima-website/docs/git.html URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/git.html?rev=1869276&r1=1869275&r2=1869276&view=diff ============================================================================== --- uima/site/trunk/uima-website/docs/git.html (original) +++ uima/site/trunk/uima-website/docs/git.html Fri Nov 1 21:30:24 2019 @@ -230,21 +230,24 @@ </td></tr> <tr><td> <blockquote class="sectionBody"> - <h2>Git notes for SVN users</h2> - <p> - See <a target="_blank" rel="noopener" href="git-svn-notes.html">git-svn-notes</a> for a brief summary of how to work - with git, if you're familiar with how to work with SVN. - </p> - <h2>Conventions</h2> + <h2>Conventions</h2> <p>See <a target="_blank" rel="noopener" href="git-conventions.html">git-conventions</a> for information about the GIT conventions being used.</p> <h2>Git Work Process</h2> - <p>See <a target="_blank" rel="noopener" href="git-work-process.html">git-work-process</a> for information on how to work with projects in GIT and submit + <p>See <a target="_blank" rel="noopener" href="git-notes.html">git-notes</a> for information on how to work with projects in GIT and submit changes and pull requests. </p> + <h2>Frequently used GIT situations and commands</h2> + <p>See <a target="_blank" rel="noopener" href="git-notes.html">git-work-process</a> for a short table of common git situations and commands. + </p> <h2>Converting a project to GIT</h2> <p>See <a target="_blank" rel="noopener" href="convert-to-git.html">convert-to-git</a> for information on the steps to take to move / convert a project from SVN to GIT.</p> <h2>Releasing when the source has been moved to GIT</h2> <p>See <a target="_blank" rel="noopener" href="git-release-notes.html">git release notes</a>.</p> + <h2>Git notes for SVN users</h2> + <p> + See <a target="_blank" rel="noopener" href="git-svn-notes.html">git-svn-notes</a> for a brief summary of how to work + with git, if you're familiar with how to work with SVN. + </p> </blockquote> </p> </td></tr> Modified: uima/site/trunk/uima-website/xdocs/git-conventions.xml URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git-conventions.xml?rev=1869276&r1=1869275&r2=1869276&view=diff ============================================================================== --- uima/site/trunk/uima-website/xdocs/git-conventions.xml (original) +++ uima/site/trunk/uima-website/xdocs/git-conventions.xml Fri Nov 1 21:30:24 2019 @@ -43,14 +43,28 @@ under the License. <p>Branches for working are typically named using the Jira issue (if there is one) associated with the work, followed by a very-short-description - enough to remind you what that jira number is about. - In addition, the name can be prefixed with the kind of work it is, e.g. <code>feature/</code> or <code>bugfix</code>. + In addition, the name can be prefixed with the kind of work it is, e.g. + <code>feature/</code> or <code>bugfix</code> or <code>refactor</code>. This can be useful in enabling you to more rapidly locate the right branch.</p> <p>After merging into master, the branch is typically deleted.</p> + <h3>Commit messages</h3> + + <p>Example: <code>[UIMA-1234] Add missing foo to bar</code></p> + + <p>Git has a two-section commit message. The first line should be a one-line id and summary. + Following that is an optional section of multiple lines that are details about the commit.</p> + + <p>The first line should start with the jira issue number including UIMA- prefix. Automatic scanners + use this to connect this to the Jira issue. You may put multiple issues if applicable. The issues may + be written with surrounding square brackets, e.g. <code>[UIMA-1234]</code>.</p> + <p>Following that should be short title of the issue, since looking back at it a reader probably won't remember + what the issue was all about. Following that can be a summary of what this particular commit does.</p> + <h4>Git merge styles</h4> <p>Different projects may use different merge styles.</p> - <p>See these links for references to common work patterns.</p> + <p>See these links for references to common work patterns. TBD</p> </section> </body> Added: uima/site/trunk/uima-website/xdocs/git-notes.xml URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git-notes.xml?rev=1869276&view=auto ============================================================================== --- uima/site/trunk/uima-website/xdocs/git-notes.xml (added) +++ uima/site/trunk/uima-website/xdocs/git-notes.xml Fri Nov 1 21:30:24 2019 @@ -0,0 +1,108 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<document> + + <properties> + <title>Git notes</title> + <author email="d...@uima.apache.org"> Apache UIMA Documentation Team</author> + </properties> + + <body> + <section name="Frequently used git actions"> + + <h2>Working with two branches in one repo</h2> + + <p>It may be best to have two separate local directories, each with a separate clone. + because if you just have one clone and switch between branches, the switch operation + the working tree might have "extra files" from the other branch, which you'll need to be + careful to ignore. In Eclipse these extra folders will look like they're waiting to be added.</p> + <p>To clone and then check-out a non-default branch, use + <pre>git clone https://... -b branch-name</pre></p> + + <h3>Alternative: Have one clone, switch between branches</h3> + <p>For example, if you have both master, and master-v2 (as is the case for core uima). + </p> + <table class="downloads"> + <tr> + <th>Goal / Task</th> + <th>Git command</th> + <th>Comments</th> + </tr> + <tr> + <td>Switch between branches</td> + <td><p>git status (to confirm things are clean)</p> + <p>git checkout <branch-name></p> + </td> + <td><p>The checkout switches to the other branch. Before you do this, please insure the working tree + has no local modifications. Otherwise the checkout command will complain. + </p> + <p>The checkout operation may not remove directories or files that are present in one branch but not in the other. + Don't remove these (Eclipse gets confused if you remove them); just don't stage them or otherwise change them. + </p> + </td> + </tr> + <tr> + <td>Create new branches for bug-fixing or features</td> + <td>see below, but do for each version</td> + <td>This is if you are independently committing changes to each branch</td> + </tr> + </table> + + <h2>Common situations</h2> + <table class="downloads"> + <tr> + <th>Goal / Task</th> + <th>Git command</th> + <th>Comments</th> + </tr> + <tr> + <td>Creating a new branch for a feature or Jira issue</td> + <td><p>git clone https:... -b master-v2</p> + <p>git checkout -t -b new-branch-name</p> + <p>git push -u origin new-branch-name</p> + </td> + <td><p>The first operation sets the base from which you will branch. + If no <code>-b branch-name</code> is specified, the default branch is used (typically master).</p> + <p>The checkout with -b will create a new branch and switch to it. The -t will + sets up the configuration so that <code>git pull</code> (with no arguments) will + pull from the starting branch (in this example, the local master-v2). + </p> + <p>The push will update the remote with the new branch. The -u operation creates the remote tracking branch, + so that <code>git push</code> will go to the corresponding new remote for this new branch. + </p> + </td> + </tr> + <tr> + <td>Undo some commits</td> + <td><p>git log --oneline</p> + <p>git reset --hard the-hash-or-ref</p> + <p>or</p> + <p>git revert the-hash-or-ref</p> + </td> + <td><p>The log command shows you the hashes for the commits, so you can find the last one you want preserved.</p> + <p>The reset should only be used if this is a local commit and hasn't been pushed.</p> + <p>The revert applies the changes needed to revert. Use it when the commit has been pushed to some public spot.</p> + </td> + </tr> + </table> + </section> + + </body> +</document> \ No newline at end of file Modified: uima/site/trunk/uima-website/xdocs/git-release-notes.xml URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git-release-notes.xml?rev=1869276&r1=1869275&r2=1869276&view=diff ============================================================================== --- uima/site/trunk/uima-website/xdocs/git-release-notes.xml (original) +++ uima/site/trunk/uima-website/xdocs/git-release-notes.xml Fri Nov 1 21:30:24 2019 @@ -94,8 +94,7 @@ under the License. <h2>release:perform</h2> <p>This does a build using the "tag" checkout, and uploads the artifacts to the maven staging repository.</p> - <p>(needs confirmation) the tag is checked out into a new branch, and the new branch is copied into - the branch being built from, in the target/checkout directory. Then the new branch is deleted.</p> + <p>The tag is cloned into the target/checkout directory</p> <p>A build is done from the target/checkout spot, with maven artifacts uploaded to repository.apache.com staging area, just like before.</p> @@ -103,23 +102,33 @@ under the License. </section> <section name="How to roll back a release attempt"> + <h2>(Optional) Reset the branch to last commit before release:prepare</h2> + <p>If you don't do this, when you do the release:prepare again, it will increment the SNAPSHOT and release numbers, + and you'll need to override those. + </p> + <p>The idea is to reset the branch being used to build, back to the commit just before the maven release:prepare commit, which is identified with the message <code>[maven-release-plugin] prepare for next development iteration</code>.</p> <p>Do this by working in a checkout of the branch being used to build, typing <code>git log</code> and finding the hash for the commit right before the prepare commit.</p> - <p></p> - <ul><li><code>git log -5 --oneline</code> shows the last 5 commits. Find the last commit before the maven prepare one.</li> + <p>Don't do this next step unless you know no one has fetched the previously pushed maven release changes. + This is typically true, because only you are working on the release.</p> + + <ul><li><code>git log -5 --oneline</code> # shows the last 5 commits. Find the last commit before the maven prepare one.</li> <li><code>git reset --hard hash-of-commit</code> where hash-of-commit is from the log </li> - <li><code>git push origin branch-name</code></li> + <li><code>git push -f origin branch-name # force needed because removing history</code></li> </ul> - + + <h2>Remove the previously created tag</h2> <p>Next, because the release:prepare created a tag, you need to remove it. Do this:</p> <ul><li><code>git tag</code> to list the tags</li> <li><code>git tag -d name-of-tag</code> to delete, e.g. uimaj-3.1.1. This deletes it locally only.</li> <li><code>git push origin :refs/tags/name-of-tag</code> to remove the tag in the remote.</li> - </ul> + </ul> + + <h2>Do any fixes, updates and then rerun the release</h2> </section> </body> Modified: uima/site/trunk/uima-website/xdocs/git.xml URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git.xml?rev=1869276&r1=1869275&r2=1869276&view=diff ============================================================================== --- uima/site/trunk/uima-website/xdocs/git.xml (original) +++ uima/site/trunk/uima-website/xdocs/git.xml Fri Nov 1 21:30:24 2019 @@ -27,24 +27,22 @@ under the License. <body> <section name="Information on GIT use by UIMA projects"> - - <h2>Git notes for SVN users</h2> - <p> - See <a target="_blank" rel="noopener" - href="git-svn-notes.html">git-svn-notes</a> for a brief summary of how to work - with git, if you're familiar with how to work with SVN. - </p> - + <h2>Conventions</h2> <p>See <a target="_blank" rel="noopener" href="git-conventions.html">git-conventions</a> for information about the GIT conventions being used.</p> - +> <h2>Git Work Process</h2> <p>See <a target="_blank" rel="noopener" - href="git-work-process.html">git-work-process</a> for information on how to work with projects in GIT and submit + href="git-notes.html">git-notes</a> for information on how to work with projects in GIT and submit changes and pull requests. </p> - + + <h2>Frequently used GIT situations and commands</h2> + <p>See <a target="_blank" rel="noopener" + href="git-notes.html">git-work-process</a> for a short table of common git situations and commands. + </p> + <h2>Converting a project to GIT</h2> <p>See <a target="_blank" rel="noopener" href="convert-to-git.html">convert-to-git</a> for information on the steps to take to move / convert a project from SVN to GIT.</p> @@ -52,6 +50,13 @@ under the License. <h2>Releasing when the source has been moved to GIT</h2> <p>See <a target="_blank" rel="noopener" href="git-release-notes.html">git release notes</a>.</p> + + <h2>Git notes for SVN users</h2> + <p> + See <a target="_blank" rel="noopener" + href="git-svn-notes.html">git-svn-notes</a> for a brief summary of how to work + with git, if you're familiar with how to work with SVN. + </p> </section>