Author: schor
Date: Wed Oct 30 14:58:01 2019
New Revision: 1869178
URL: http://svn.apache.org/viewvc?rev=1869178&view=rev
Log:
no jira - update git processes including how to release
Modified:
uima/site/trunk/uima-website/docs/convert-to-git.html
uima/site/trunk/uima-website/docs/git-release-notes.html
uima/site/trunk/uima-website/docs/git-svn-notes.html
uima/site/trunk/uima-website/docs/git-work-process.html
uima/site/trunk/uima-website/xdocs/convert-to-git.xml
uima/site/trunk/uima-website/xdocs/git-release-notes.xml
uima/site/trunk/uima-website/xdocs/git-svn-notes.xml
uima/site/trunk/uima-website/xdocs/git-work-process.xml
Modified: uima/site/trunk/uima-website/docs/convert-to-git.html
URL:
http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/convert-to-git.html?rev=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/convert-to-git.html (original)
+++ uima/site/trunk/uima-website/docs/convert-to-git.html Wed Oct 30 14:58:01
2019
@@ -231,9 +231,16 @@
<tr><td>
<blockquote class="sectionBody">
<p>This describes the various steps needed
in converting a project from SVN to GIT.</p>
- <h3>Setup Read-only mirror, if
not already done</h3>
<h3>File INFRA Jira ticket to
convert read-only mirror to r/w</h3>
+ <p>Tell the dev list this is
happening, so people should not make any changes until the conversion is done.
+ This may take 2-3 weeks, depending on INFRA workload.</p>
+ <p>Prior to doing the ticket,
if you want the top level named "master" instead of "trunk", do that change
+ in SVN, and let it propogate to the read-only mirror (if one exists).
This will save time after the
+ migration, because renames involve help from INFRA.</p>
<h3>File INFRA Jira tickets
for additional setup or fixups</h3>
+ <p>If a rename is needed at
this point for master/trunk, you'll need to ask INFRA to protect master
+ after the rename, and to set it as the default (removing trunk as the
default). Once INFRA does this,
+ you can delete the old trunk.</p>
<h4>Renaming Branches</h4>
<p>In SVN, the main work goes
into a spot under the name "trunk". The convention in git is to name this
the "master".</p>
@@ -254,6 +261,17 @@
https://help.github.com/en/articles/about-protected-branches</a>.</p>
<p>Individual projects within
UIMA may request additional branch protection settings be set, via
INFRA Jira issues.</p>
+ <h3>Updating POMs for GIT</h3>
+ <p>POMs have an <scm>
element that points to svn, and it should be updated as follows:
+ </p>
+ <ul>
+ <li>For both the connection and developerConnection:
+
<p><code>scm:git:https://github.com/apache/...proj-name.../...subdir...</code></p>
+ </li>
+ <li>For the url: this should point to the source code at github, e.g.
+
<p><code>https://github.com/apache/...proj-name.../tree/master/...sub-proj-name...</code></p>
+ <p>For uima-v2, replace <code>master</code> with
<code>master-v2</code></p></li>
+ </ul>
</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=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/git-release-notes.html (original)
+++ uima/site/trunk/uima-website/docs/git-release-notes.html Wed Oct 30
14:58:01 2019
@@ -232,14 +232,83 @@
<blockquote class="sectionBody">
<p>Tags are stored in the .git folder in
the subfolder /refs/tags.</p>
<p>When Apache Infra sets up a
writable git project, they set
- <a target="_blank" rel="nofollow noopener"
href="https://help.github.com/en/github/administering-a-repository/about-protected-branches";>
- github protection</a>. The protection is set on
- <ul><li>refs/heads/trunk</li>
- <li>refs/heads/master</li>
- <li>refs/heads/rel/</li>
- <li>refs/tags/rel/</li>
- </ul>
- </p>
+ <a target="_blank" rel="nofollow noopener"
href="https://help.github.com/en/github/administering-a-repository/about-protected-branches";>
+ github protection</a>. The protection is set on
+ <ul><li>refs/heads/trunk</li>
+ <li>refs/heads/master</li>
+ <li>refs/heads/rel/</li>
+ <li>refs/tags/rel/</li>
+ </ul>
+ </p>
+ <p>After a release passes,
make a new tag for the release with the name rel/...tag-name... Here's how:</p>
+ <ul><li><code>git tag -m
"proj-name-1.2.3 rcXXX released" rel/proj-name-x.y.z proj-name-x.y.z^{}</code>
+ The strange notation ^{} peels the annotated tag and returns a
ref to the actual commit.</li>
+ <li><code>git push origin rel/proj-name-x.y.z</code> This
updates the new tag to the remote repo</li>
+ </ul>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="What the maven release plugin does with GIT"><h1><img
src="images/UIMA_4sq50tightCropSolid.png"/> What the maven release plugin
does with GIT</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <h2>release:prepare</h2>
+ <p>
+ <ul>
+ <li>Take all the poms in the project which start out at some
x.y.z-SNAPSHOT version, and
+ update the versions to x.y.z (without the -SNAPSHOT).</li>
+ <li>Build the project.</li>
+ </ul>
+ </p>
+ <p>
+ <ul>
+ <li>Create a commit with all the updated POMs, and commit that to
whatever branch was checked out at the start.</li>
+ <li>git push</li>
+ <li>Create a tag</li>
+ <li>git push</li>
+ </ul>
+ </p>
+ <p>
+ <ul>
+ <li>Update all the poms to x.y.z + 0.0.1 -SNAPSHOT, and commit
them</li>
+ <li>git push</li>
+ </ul>
+ </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>A build is done from the
target/checkout spot, with maven artifacts uploaded to repository.apache.com
staging area,
+ just like before.</p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="How to roll back a release attempt"><h1><img
src="images/UIMA_4sq50tightCropSolid.png"/> How to roll back a release
attempt</h1></a>
+ </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
+ 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>
+ <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>
+ </ul>
+ <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>
</blockquote>
</p>
</td></tr>
Modified: uima/site/trunk/uima-website/docs/git-svn-notes.html
URL:
http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/git-svn-notes.html?rev=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/git-svn-notes.html (original)
+++ uima/site/trunk/uima-website/docs/git-svn-notes.html Wed Oct 30 14:58:01
2019
@@ -386,7 +386,7 @@
<p>git reset --hard hash-of-commit</p>
<p>git push -f origin branch-name</p>
</td>
- <td>This method is only used when no one has cloned the branch-name.
Typical use: when
+ <td>The "-f" is needed to move the remote HEAD backwards. This method
is only used when no one has cloned the branch-name. Typical use: when
a release:prepare has been done which needs to be rolled back.
</td>
</tr>
Modified: uima/site/trunk/uima-website/docs/git-work-process.html
URL:
http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/git-work-process.html?rev=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/git-work-process.html (original)
+++ uima/site/trunk/uima-website/docs/git-work-process.html Wed Oct 30 14:58:01
2019
@@ -239,7 +239,8 @@
<h2>Fork the repo</h2>
<p>The first step is to fork
the project on githhub. To do this, point your browser to the repository,
and press the fork button.
- <img src="./images/git/fork.png" alt="fork button" /></p>
+ </p>
+ <img
src="./images/git/fork.png" alt="fork button" />
<p>This will fork (create a
writable-by-you) copy of the repo, in your personal github account.
</p>
<h2>Clone the fork</h2>
@@ -255,7 +256,7 @@
new branch. The git command to do these two steps in one command is
<code>git checkout -b the-new-branch-name</code></p>
<p>The reason to work in a
branch is to keep changes related to one issue separate from other
- work. If you were also not working on a fork, but on the main project,
this practice separates the
+ work. If you were also not working on a fork, but on the main project,
this practice would also separate the
changes from the "production-ready" master branch, until things have
been reviewed and tested.</p>
<h2>Make your changes</h2>
<p>Now make your changes. You
can commit the changes as you desire, and push them to your forked copy.</p>
Modified: uima/site/trunk/uima-website/xdocs/convert-to-git.xml
URL:
http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/convert-to-git.xml?rev=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/convert-to-git.xml (original)
+++ uima/site/trunk/uima-website/xdocs/convert-to-git.xml Wed Oct 30 14:58:01
2019
@@ -29,12 +29,19 @@ under the License.
<section name="Converting a project to GIT">
<p>This describes the various steps needed in converting a project from
SVN to GIT.</p>
-
- <h3>Setup Read-only mirror, if not already done</h3>
-
+
<h3>File INFRA Jira ticket to convert read-only mirror to r/w</h3>
+ <p>Tell the dev list this is happening, so people should not make any
changes until the conversion is done.
+ This may take 2-3 weeks, depending on INFRA workload.</p>
+
+ <p>Prior to doing the ticket, if you want the top level named "master"
instead of "trunk", do that change
+ in SVN, and let it propogate to the read-only mirror (if one exists).
This will save time after the
+ migration, because renames involve help from INFRA.</p>
<h3>File INFRA Jira tickets for additional setup or fixups</h3>
+ <p>If a rename is needed at this point for master/trunk, you'll need to
ask INFRA to protect master
+ after the rename, and to set it as the default (removing trunk as the
default). Once INFRA does this,
+ you can delete the old trunk.</p>
<h4>Renaming Branches</h4>
<p>In SVN, the main work goes into a spot under the name "trunk". The
convention in git is to name this
@@ -65,7 +72,17 @@ under the License.
<p>Individual projects within UIMA may request additional branch
protection settings be set, via
INFRA Jira issues.</p>
-
+ <h3>Updating POMs for GIT</h3>
+ <p>POMs have an <scm> element that points to svn, and it should be
updated as follows:
+ </p>
+ <ul>
+ <li>For both the connection and developerConnection:
+
<p><code>scm:git:https://github.com/apache/...proj-name.../...subdir...</code></p>
+ </li>
+ <li>For the url: this should point to the source code at github, e.g.
+
<p><code>https://github.com/apache/...proj-name.../tree/master/...sub-proj-name...</code></p>
+ <p>For uima-v2, replace <code>master</code> with
<code>master-v2</code></p></li>
+ </ul>
</section>
</body>
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=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/git-release-notes.xml (original)
+++ uima/site/trunk/uima-website/xdocs/git-release-notes.xml Wed Oct 30
14:58:01 2019
@@ -28,17 +28,80 @@ under the License.
<section name="Tags">
- <p>Tags are stored in the .git folder in the subfolder /refs/tags.</p>
-
- <p>When Apache Infra sets up a writable git project, they set
- <a target="_blank" rel="nofollow noopener"
href="https://help.github.com/en/github/administering-a-repository/about-protected-branches";>
- github protection</a>. The protection is set on
- <ul><li>refs/heads/trunk</li>
- <li>refs/heads/master</li>
- <li>refs/heads/rel/</li>
- <li>refs/tags/rel/</li>
- </ul>
- </p>
+ <p>Tags are stored in the .git folder in the subfolder
/refs/tags.</p>
+
+ <p>When Apache Infra sets up a writable git project, they set
+ <a target="_blank" rel="nofollow noopener"
href="https://help.github.com/en/github/administering-a-repository/about-protected-branches";>
+ github protection</a>. The protection is set on
+ <ul><li>refs/heads/trunk</li>
+ <li>refs/heads/master</li>
+ <li>refs/heads/rel/</li>
+ <li>refs/tags/rel/</li>
+ </ul>
+ </p>
+
+ <p>After a release passes, make a new tag for the release with the
name rel/...tag-name... Here's how:</p>
+ <ul><li><code>git tag -m "proj-name-1.2.3 rcXXX released"
rel/proj-name-x.y.z proj-name-x.y.z^{}</code>
+ The strange notation ^{} peels the annotated tag and returns a
ref to the actual commit.</li>
+ <li><code>git push origin rel/proj-name-x.y.z</code> This
updates the new tag to the remote repo</li>
+ </ul>
+ </section>
+
+ <section name="What the maven release plugin does with GIT">
+ <h2>release:prepare</h2>
+ <p>
+ <ul>
+ <li>Take all the poms in the project which start out at some
x.y.z-SNAPSHOT version, and
+ update the versions to x.y.z (without the -SNAPSHOT).</li>
+ <li>Build the project.</li>
+ </ul>
+ </p>
+
+ <p>
+ <ul>
+ <li>Create a commit with all the updated POMs, and commit that to
whatever branch was checked out at the start.</li>
+ <li>git push</li>
+ <li>Create a tag</li>
+ <li>git push</li>
+ </ul>
+ </p>
+
+ <p>
+ <ul>
+ <li>Update all the poms to x.y.z + 0.0.1 -SNAPSHOT, and commit
them</li>
+ <li>git push</li>
+ </ul>
+ </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>A build is done from the target/checkout spot, with maven artifacts
uploaded to repository.apache.com staging area,
+ just like before.</p>
+
+ </section>
+
+ <section name="How to roll back a release attempt">
+ <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>
+ <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>
+ </ul>
+
+ <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>
</section>
</body>
Modified: uima/site/trunk/uima-website/xdocs/git-svn-notes.xml
URL:
http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git-svn-notes.xml?rev=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/git-svn-notes.xml (original)
+++ uima/site/trunk/uima-website/xdocs/git-svn-notes.xml Wed Oct 30 14:58:01
2019
@@ -190,7 +190,7 @@ under the License.
<p>git reset --hard hash-of-commit</p>
<p>git push -f origin branch-name</p>
</td>
- <td>This method is only used when no one has cloned the branch-name.
Typical use: when
+ <td>The "-f" is needed to move the remote HEAD backwards. This method
is only used when no one has cloned the branch-name. Typical use: when
a release:prepare has been done which needs to be rolled back.
</td>
</tr>
Modified: uima/site/trunk/uima-website/xdocs/git-work-process.xml
URL:
http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git-work-process.xml?rev=1869178&r1=1869177&r2=1869178&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/git-work-process.xml (original)
+++ uima/site/trunk/uima-website/xdocs/git-work-process.xml Wed Oct 30 14:58:01
2019
@@ -41,7 +41,8 @@ under the License.
<h2>Fork the repo</h2>
<p>The first step is to fork the project on githhub. To do this, point
your browser to the repository,
and press the fork button.
- <img src="./images/git/fork.png" alt="fork button" /></p>
+ </p>
+ <img src="./images/git/fork.png" alt="fork button" />
<p>This will fork (create a writable-by-you) copy of the repo, in your
personal github account.
</p>
@@ -61,7 +62,7 @@ under the License.
<code>git checkout -b the-new-branch-name</code></p>
<p>The reason to work in a branch is to keep changes related to one issue
separate from other
- work. If you were also not working on a fork, but on the main project,
this practice separates the
+ work. If you were also not working on a fork, but on the main project,
this practice would also separate the
changes from the "production-ready" master branch, until things have
been reviewed and tested.</p>
<h2>Make your changes</h2>
