You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2019/09/09 17:51:10 UTC
svn commit: r1866703 - in /uima/site/trunk/uima-website:
docs/convert-to-git.html docs/git-svn-notes.html docs/git.html
xdocs/convert-to-git.xml xdocs/git-svn-notes.xml xdocs/git.xml
Author: schor
Date: Mon Sep 9 17:51:10 2019
New Revision: 1866703
URL: http://svn.apache.org/viewvc?rev=1866703&view=rev
Log:
no Jira - add Git info, including updated version of the google docs spreadsheet done some time ago
Added:
uima/site/trunk/uima-website/docs/git-svn-notes.html
uima/site/trunk/uima-website/xdocs/git-svn-notes.xml
Modified:
uima/site/trunk/uima-website/docs/convert-to-git.html
uima/site/trunk/uima-website/docs/git.html
uima/site/trunk/uima-website/xdocs/convert-to-git.xml
uima/site/trunk/uima-website/xdocs/git.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=1866703&r1=1866702&r2=1866703&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/convert-to-git.html (original)
+++ uima/site/trunk/uima-website/docs/convert-to-git.html Mon Sep 9 17:51:10 2019
@@ -235,10 +235,25 @@
<h3>File INFRA Jira ticket to convert read-only mirror to r/w</h3>
<h3>File INFRA Jira tickets for additional setup or fixups</h3>
<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>
+ <p>GIT renaming cannot be done directly by users if the branch is "protected";
+ you must instead request it be done via an INFRA issue. This may take some time; see the kanban
+ board on the INFRA jira to get a sense of how many other requests are in front of yours.</p>
+ <blockquote>Therefore, it would be good to rename things yourself (e.g. in SVN).</blockquote>
<h3>Add .gitignore and .gitattributes</h3>
<p>These files should be added to the top (outer-most) containing folder for the projects in your repo.
They will be default apply to all subfolders. If you need to, you can override these settings in a subfolder.</p>
<p>Copy these files from some already converted repo.</p>
+ <h3>Dealing with protected branches</h3>
+ <p>The default, when converting a project from svn to git is to set "protection" for
+ the master branch and things called refs/heads/rel/ and refs/tags/rel/.
+ </p>
+ <p>The protection is described here:
+ <a target="_blank" rel="nofollow noopener" href="https://help.github.com/en/articles/about-protected-branches">
+ 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>
</blockquote>
</p>
</td></tr>
Added: 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=1866703&view=auto
==============================================================================
--- uima/site/trunk/uima-website/docs/git-svn-notes.html (added)
+++ uima/site/trunk/uima-website/docs/git-svn-notes.html Mon Sep 9 17:51:10 2019
@@ -0,0 +1,480 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "https://www.w3.org/TR/html4/loose.dtd">
+
+
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+ <style type="text/css">@import "stylesheets/base.css";</style>
+ <meta name="author" value=" Apache UIMA Documentation
+ Team">
+ <meta name="email" value="dev@uima.apache.org">
+
+
+
+ <title>Apache UIMA - GIT SVN Notes</title>
+
+ <!-- Begin Cookie Consent plugin by Silktide - https://silktide.com/cookieconsent -->
+ <!-- Commented out because implied consent is not compatible with GDPR -->
+ <!--
+ <script type="text/javascript">
+ window.cookieconsent_options = {"message":"This website uses cookies to ensure you get the best experience on our website","dismiss":"Got it!","learnMore":"More info","link":"https://uima.apache.org/privacy-policy.html","theme":"dark-bottom"};
+ </script>
+
+ <script type="text/javascript" src="/cookieconsent2/cookieconsent.min.js"></script>
+ -->
+ <!-- End Cookie Consent plugin -->
+
+ <!-- Begin Google Analytics -->
+ <!-- Commented out because GA requires consent according to GDPR -->
+ <!--
+ <script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-70846351-1', 'auto');
+ ga('set', 'anonymizeIp', true);
+ ga('send', 'pageview');
+
+ </script>
+ -->
+ <!-- End Google Analytics -->
+ </head>
+
+ <body>
+ <div class="topLogos">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <a href="index.html">
+ <img style="border: 1px solid black;" src="./images/UIMA_banner2tlpTm.png" alt="UIMA project logo" border="0"/>
+ </a>
+ </td>
+ <td align='CENTER'>
+ <div class="pageBanner">GIT SVN Notes</div>
+ </td>
+ <td align='RIGHT'>
+ <a href="https://www.apache.org">
+ <img src="./images/asf-logo-on-white-smallTm.png" alt="Apache UIMA" border="0"/>
+ </a>
+ </td>
+ </tr>
+ </table>
+ <hr noshade="" size="1"/>
+ </div>
+ <table border="0" width="100%" cellspacing="4">
+ <tr>
+ <td align='RIGHT' colspan="2">
+ <form method="get" action="https://www.google.com/search">
+ Search the site
+ <input type="text" name="q" size="25" maxlength="255" value="" />
+ <input type="hidden" name="sitesearch" value="https://uima.apache.org/" />
+ <input name="Search" value="Search Site" type="submit"/>
+ </form>
+ </td>
+ </tr>
+ <tr> <!-- LEFT SIDE NAVIGATION -->
+ <td width="20%" valign="top">
+
+
+
+
+
+
+ <!-- regular menu -->
+ <div class="navBar">
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">General</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./index.html">Home</a>
+ </div>
+ <div class="navBarItem"> <a href="./downloads.cgi">Downloads</a>
+ </div>
+ <div class="navBarItem"> <a href="./documentation.html">Documentation</a>
+ </div>
+ <div class="navBarItem"> <a href="./news.html">News</a>
+ </div>
+ <div class="navBarItem"> <a href="./publications.html">Publications</a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="https://issues.apache.org/jira/browse/uima" target="_blank" rel="noopener">Issue tracker <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="https://cwiki.apache.org/confluence/display/UIMA/" target="_blank" rel="noopener">Wiki <img src="images/offsitelink.png"/></a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="https://cwiki.apache.org/confluence/display/UIMA/Powered+by+Apache+UIMA" target="_blank" rel="noopener">Powered By UIMA <img src="images/offsitelink.png"/></a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Community</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./get-involved.html">Get Involved</a>
+ </div>
+ <div class="navBarItem"> <a href="./mail-lists.html">Mailing Lists</a>
+ </div>
+ <div class="navBarItem"> <a href="./contribution-policy.html">Contribution Policies</a>
+ </div>
+ <div class="navBarItem"> <a href="./faq.html">FAQ</a>
+ </div>
+ <div class="navBarItem"> <a href="./project-guidelines.html">Project Guidelines</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Scaleout Frameworks</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./doc-uimaas-what.html">UIMA-AS</a>
+ </div>
+ <div class="navBarItem"> <a href="./doc-uimaducc-whatitam.html">UIMA-DUCC</a>
+ </div>
+ <div class="navBarItem"> <a href="./doc-uimaducc-demo.html">..Demo Page</a>
+ </div>
+ <div class="navBarItem"> <a href="http://uima-ducc-demo.apache.org:42133" target="_blank" rel="noopener">..Demo Live <img src="images/offsitelink.png"/></a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Components & Tools</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./sandbox.html#uima-addons-annotators">Annotators</a>
+ </div>
+ <div class="navBarItem"> <a href="./toolsServers.html">Tools & Servers</a>
+ </div>
+ <div class="navBarItem"> <a href="./sandbox.html">Addons and Sandbox</a>
+ </div>
+ <div class="navBarItem"> <a href="./ruta.html">UIMA Ruta</a>
+ </div>
+ <div class="navBarItem"> <a href="./uimafit.html">uimaFIT</a>
+ </div>
+ <div class="navBarItem"> <a href="./external-resources.html">External Resources</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Development</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./dev-quick.html">Quick Start: building</a>
+ </div>
+ <div class="navBarItem"> <a href="./building-uima.html">Building from Source</a>
+ </div>
+ <div class="navBarItem"> <a href="./one-time-setup.html">One-time setups</a>
+ </div>
+ <div class="navBarItem"> <a href="./svn.html">Source Code</a>
+ </div>
+ <div class="navBarItem"> <a href="./distribution.html">Creating a Distribution</a>
+ </div>
+ <div class="navBarItem"> <a href="./release.html">Doing a UIMA release</a>
+ </div>
+ <div class="navBarItem"> <a href="https://www.apache.org/security/committers.html" target="_blank" rel="noopener">Doing a CVE (Apache) <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="./eclipse-update-site.html">Eclipse Update Sites</a>
+ </div>
+ <div class="navBarItem"> <a href="./git.html">GIT</a>
+ </div>
+ <div class="navBarItem"> <a href="./codeConventions.html">Code Conventions</a>
+ </div>
+ <div class="navBarItem"> <a href="./uima-specification.html">UIMA Specification (OASIS)</a>
+ </div>
+ <div class="navBarItem"> <a href="./team-list.html">Project Team</a>
+ </div>
+ <div class="navBarItem"> <a href="./maven-design.html">Maven Use</a>
+ </div>
+ <div class="navBarItem"> <a href="./updating-website.html">Updating this Website</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Events and Conferences</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./coling14.html">COLING 2014</a>
+ </div>
+ <div class="navBarItem"> <a href="./gscl13.html">GSCL 2013</a>
+ </div>
+ <div class="navBarItem"> <a href="./iks09.html">IKS 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./gscl09.html">GSCL 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lsm09.html">LSM 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lrec08.html">LREC 2008</a>
+ </div>
+ <div class="navBarItem"> <a href="./gldv07.html">GLDV 2007</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">ASF</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="https://www.apache.org/licenses/" target="_blank" rel="noopener">License <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener">ASF Sponsors <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener">ASF Sponsorship <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="./security_report">Security</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td width="80%" align="left" valign="top">
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="GIT SVN Notes"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> GIT SVN Notes</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <h2>Names and IDs in Git</h2>
+ <p>Systems that hold git repos, like github.com, or gitbox.a.o, each have their own way of
+ logging in and authenticating. For github.com, 2 factor authentication is required in order
+ to write to Apache repos - see
+ <a target="_blank" rel="nofollow noopener" href="https://gitbox.apache.org/">
+ https://gitbox.apache.org/</a>.</p>
+ <p>The name used for logging in is separate from the name used to identify each commit in
+ git. These crendentials are called your "identity" and are
+ the combination of a username and "email". These can be set globally for all repos
+ in your local machine, or locally, per repository.
+ See <a target="_blank" rel="nofollow noopener" href="https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup">
+ https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup</a>.</p>
+ <h3>Using multiple git identities</h3>
+ <p>You may work with different organizations, and want to have different identities for each
+ repository, depending. You can do this; just use the local git configuration for the repo to
+ specify this.</p>
+ <h2>Recent GIT changes</h2>
+ <p><sl><li><p><code>git switch</code></p></li>
+ <li><p><code>git restore</code></p></li>
+ </sl>
+
+ <blockquote>June 2019: git 2.23 release - has new switch/restore
+ commands, to be used in place of git checkout; see
+ <a target="_blank" rel="nofollow noopener" href="https://github.blog/2019-08-16-highlights-from-git-2-23/">
+ https://github.blog/2019-08-16-highlights-from-git-2-23/</a>.
+ </blockquote>
+ </p>
+ <h2>GIT vs SVN</h2>
+ <p>Note in this table, that the various commands usually have many options (especially git)
+ which can change their behavior substantially. This table frequently is only showing
+ one of the main uses of the git commands. When in doubt, please google the command
+ (e.g. google <code>git branch</code>) to see all the other things a git command can do.</p>
+ <table class="downloads">
+ <tr>
+ <th>Goal / Task</th>
+ <th>SVN</th>
+ <th>Git/GitHub</th>
+ <th>Comments/Discussion/Comparisons</th>
+ </tr>
+ <tr>
+ <td>checkout</td>
+ <td>svn checkout <url-of-a-branch></td>
+ <td><p>git clone <repo-url>
+ </p>
+ <p>git clone <repo-url> -branch <branch-name>
+ </p>
+ </td>
+ <td><p>SVN checkout
+ <ol><li>making a working tree of the contents of some (usually remote) repository</li>
+ <li>updating an existing working tree to the "head" level of the repository, to
+ catch up with any changes made by others.</li>
+ </ol>
+ </p>
+ <p>Git has distributed repositories; to get a local working tree, you first need to have a local
+ clone of a (usually remote) repository.
+ The clone operation creates a full (all branches, tags, etc.) copy of the remote repository
+ onto the local machine.
+ Subsequently, the default branch (or a specific branch) is checked out into the working tree.
+ </p>
+ </td>
+
+ </tr>
+ <tr>
+ <td>update to current</td>
+ <td>svn update</td>
+ <td>git pull</td>
+ <td><p>Update makes the working tree have the same level as the remote.</p>
+ <p>SVN update may cause merging to occur, and merge conflicts which are resolved by hand.</p>
+ <p>git pull does this in a 2 step process:
+ <ul><li>In step 1 it does a <code> git fetch </code> which updates the part of the local git repo that
+ are tracking the remote, to matching the current data at the remote
+ (by default, it does this for all branches). </li>
+ <li>In step 2, it does a <code> git merge </code> which merges the remote-tracking branch(s) which changed with
+ any corresponding local branch(s).
+ This may result in merge conflicts which will need manual resolving.
+ If there are conflicting changes, then there are two options:
+ <ol><li>stash the changes, pull, then apply the stash, then resolve conflicts</li>
+ <li>commit the local changes, pull, resolve conflicts</li>
+ </ol>
+
+ </li></ul>
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>commit</td>
+ <td>svn commit</td>
+ <td><p>git commit</p>
+ <p>git push</p></td>
+ <td><p>SVN commit uploads changes from the working tree to the remote repo.
+ It fails if the remote repo's files are beyond the working-tree's checkout level;
+ in this case an svn update is needed first before the commit can be done.
+ <ul><li>The update may create merge conflicts which will need to be resolved before the commit can happen.</li></ul>
+ </p>
+
+ <p>
+ A git commit commits the (staged) changes in the working tree to the local repository branch.
+ <ul><li>Eclipse team plugin for git allows you to
+ stage any unstaged items before doing the commit.</li></ul>
+ </p>
+ <p>A <code>git push</code> transfer the changes from the local repository up to the
+ the remote one, provided that those changes can be done using fast-forward.
+ Otherwise, like SVN, this operation fails. Fix this the same way, by doing a git pull
+ and addressing any merge issues.</p>
+ <p>
+ The local repo can be configured to talk to any number of other local or remote repositories
+ to sync with them.
+ However, most of the time, it is only configured to sync with a single canonical remote repo,
+ e.g. on GitHub.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>tag</td>
+ <td>svn copy <url>/trunk <url>/tags/<tag-name></td>
+ <td>git tag <tag-name></td>
+ <td><p>Tags are first-class citizens in git and represent a state of the repository.
+ In SVN, tags are just another folder and a manifestation of a folder naming convention.
+ </p>
+ </td>
+
+ </tr>
+ <tr>
+ <td>branch</td>
+ <td>svn copy <url>/trunk <url>/branches/<branch-namel></td>
+ <td>git branch <branch-name></td>
+ <td>Creating a branch does not "switch" the current checkout to the branch. See switch.</td>
+ </tr>
+ <tr>
+ <td>switch</td>
+ <td>svn switch <url></td>
+ <td>git switch <branch></td>
+ <td><p>SVN switch updates the local working tree (or portions of it) to some remote repo spot.</p>
+ <p>git switch is at the granularity of a branch.
+ The working tree and the git "index" of to-be-committed things are updated to match the new branch.
+ The <code>switch</code> command is a refactoring of the git checkout command; see
+ <a target="_blank" rel="nofollow noopener" href="https://github.blog/2019-08-16-highlights-from-git-2-23/">
+ https://github.blog/2019-08-16-highlights-from-git-2-23/</a>.
+ </p>
+ <p>Switch updates the local checkout to a different branch, preserving any changes not yet checked (maybe showing conflict editor), and changing where a commit will go with the same SVN repo.
+ git switch replaces the checkout tree (except for untracked things) with the branch/tag/revision.
+ If this would lose data (because you have uncommitted changes), the checkout is not done (error msg).</p>
+ </td>
+ </tr>
+ <tr>
+ <td>relocate (when the URL of the remote repo has changed)</td>
+ <td>svn relocate <from-url> <to-url></td>
+ <td>git remote set-url origin <remote-url></td>
+ <td><p>The git remote set-url associates a remote with a name, such as origin, which
+ by convention is used by default for many operations involving remotes.</p></td>
+ </tr>
+ <tr>
+ <td>change the commit message</td>
+ <td>svn propset, eclipse: in team history view</td>
+ <td>git commit amend - changes the last commit message</td>
+ <td><p>In SVN, it is easy to update the properties (commit messages) of any past commit.
+ In git, this is possible but intentionally difficult.
+ The version history in git is covered by cryptographic hashes.
+ In order for the distributed version control to work well,
+ it is essential that the hashes are consistent across all clones of the repositories.
+ If they are not, manual intervention is necessary.
+ </p>
+ <p>
+ Rewriting the commit message is fine, as long as the commit is only to your private
+ local repo. But it will cause problems if it has been "published" (that is, pushed to a
+ remote repo, where others might have downloaded it). Because of this,
+ it is highly discouraged to re-write git histories and only possible using a "force push".
+ For this reason, shared branches such as the "master" branch or maintenance branches
+ are usually "protected", meaning that force-pushes are rejected.
+ But since it is not uncommon that things need to be rewritten,
+ it is usually accepted that people force-push changes into feature branches they work on.
+ But it should still be avoided, in particular if there are others
+ contributing to the same feature branch.</p></td>
+ </tr>
+ <tr>
+ <td>submitting a patch</td>
+ <td><p>Create a Jira issue</p>
+ <p>implement changes</p>
+ <p>svn diff</p>
+ <p>attach that diff to Jira issue</p>
+ </td>
+ <td><p>Create a Jira issue</p>
+ <p>
+ Create a branch following naming convention:<br />
+ e.g. feature/UIMA-1234-cool-new-feature</p>
+ <p>commit any changes for the patch to that branch</p>
+ <p>push the branch to remote</p>
+ <p>create a pull request via GitHub site</p>
+ <p>wait for the CI (Continuous Integration) process to
+ finish any checking/testing of the pull request</p>
+ <p>ask for a review (if you are not a committer)</p>
+ <p>make changes (if needed) and repeat review</p>
+ <p>merge the pull request (or ask a committer to do it)</p>
+ </td>
+ <td>
+ <p>With the SVN-based infrastructure that is in place at te ASF, diffs need to be handled manually.
+ I.e. contributors need to create them,
+ committers need to apply them, review them, run test builds,
+ and the process repeats if changes need to be made.
+ </p>
+ <p>In GitHub contributions are made through pull requests;
+ these are required (vs just doing git push) when the branch being pushed to is
+ marked as "protected". By convention, the release branches and tags, and the "master" are
+ marked this way. This is changed/managed by filing a Jira issue with INFRA.
+ </p>
+ <p>While working on a feature or bug fix in a separate branch, simple pushes can be used.</p>
+ <p>
+ A pull request provides the ability to
+ discuss changes in pull requests, perform reviews, and run automated checks.
+ </p>
+ <p>The ASF Jenkins is already set up to automatically monitor pull requests
+ and to run automated checks on them. For security reasons,
+ pull requests from non-committers are not built automatically but must be triggered by a committer
+ by posting a comment such as "Jenkins, can you test this please."
+ to the discussion thread of the pull request on the GitHub website.
+ </p>
+ </td>
+ </tr>
+ </table>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ </td>
+ </tr>
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <table class="pageFooter">
+ <tr>
+ <td><a href="index.html">Home</a></td>
+ <td><a href="privacy-policy.html">Privacy Policy</a></td>
+ <td style="font-size:75%">
+ Copyright © 2006-2013, The Apache Software Foundation.<br/>
+ Apache UIMA, UIMA, the Apache UIMA logo and the Apache Feather logo are trademarks of The Apache Software Foundation.<br/>
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </td>
+ <td><a href="mailto:dev@uima.apache.org">Contact us</a></td>
+ </tr>
+ </table>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+
Modified: uima/site/trunk/uima-website/docs/git.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/git.html?rev=1866703&r1=1866702&r2=1866703&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/git.html (original)
+++ uima/site/trunk/uima-website/docs/git.html Mon Sep 9 17:51:10 2019
@@ -230,10 +230,15 @@
</td></tr>
<tr><td>
<blockquote class="sectionBody">
- <h2>Conventions</h2>
- <p>See <a target="_blank" rel="noopener" href="git-conventions">git-conventions</a> for information about the GIT conventions being used.</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>
+ <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>Converting a project to GIT</h2>
- <p>See <a target="_blank" rel="noopener" href="convert-to-git">convert-to-git</a> for information on the steps to take to move / convert a project from SVN to GIT.</p>
+ <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>
</blockquote>
</p>
</td></tr>
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=1866703&r1=1866702&r2=1866703&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/convert-to-git.xml (original)
+++ uima/site/trunk/uima-website/xdocs/convert-to-git.xml Mon Sep 9 17:51:10 2019
@@ -37,13 +37,35 @@ under the License.
<h3>File INFRA Jira tickets for additional setup or fixups</h3>
<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>
+
+ <p>GIT renaming cannot be done directly by users if the branch is "protected";
+ you must instead request it be done via an INFRA issue. This may take some time; see the kanban
+ board on the INFRA jira to get a sense of how many other requests are in front of yours.</p>
+
+ <blockquote>Therefore, it would be good to rename things yourself (e.g. in SVN).</blockquote>
<h3>Add .gitignore and .gitattributes</h3>
<p>These files should be added to the top (outer-most) containing folder for the projects in your repo.
They will be default apply to all subfolders. If you need to, you can override these settings in a subfolder.</p>
<p>Copy these files from some already converted repo.</p>
-
+
+ <h3>Dealing with protected branches</h3>
+
+ <p>The default, when converting a project from svn to git is to set "protection" for
+ the master branch and things called refs/heads/rel/ and refs/tags/rel/.
+ </p>
+ <p>The protection is described here:
+ <a target="_blank" rel="nofollow noopener"
+ href="https://help.github.com/en/articles/about-protected-branches">
+ 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>
+
+
</section>
</body>
Added: 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=1866703&view=auto
==============================================================================
--- uima/site/trunk/uima-website/xdocs/git-svn-notes.xml (added)
+++ uima/site/trunk/uima-website/xdocs/git-svn-notes.xml Mon Sep 9 17:51:10 2019
@@ -0,0 +1,261 @@
+<?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 SVN Notes</title>
+ <author email="dev@uima.apache.org"> Apache UIMA Documentation
+ Team</author>
+</properties>
+
+<body>
+
+ <section name="GIT SVN Notes">
+
+ <h2>Names and IDs in Git</h2>
+ <p>Systems that hold git repos, like github.com, or gitbox.a.o, each have their own way of
+ logging in and authenticating. For github.com, 2 factor authentication is required in order
+ to write to Apache repos - see
+ <a target="_blank" rel="nofollow noopener" href="https://gitbox.apache.org/">
+ https://gitbox.apache.org/</a>.</p>
+
+ <p>The name used for logging in is separate from the name used to identify each commit in
+ git. These crendentials are called your "identity" and are
+ the combination of a username and "email". These can be set globally for all repos
+ in your local machine, or locally, per repository.
+ See <a target="_blank" rel="nofollow noopener" href="https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup">
+ https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup</a>.</p>
+
+ <h3>Using multiple git identities</h3>
+ <p>You may work with different organizations, and want to have different identities for each
+ repository, depending. You can do this; just use the local git configuration for the repo to
+ specify this.</p>
+
+ <h2>Recent GIT changes</h2>
+ <p><sl><li><p><code>git switch</code></p></li>
+ <li><p><code>git restore</code></p></li>
+ </sl>
+
+ <blockquote>June 2019: git 2.23 release - has new switch/restore
+ commands, to be used in place of git checkout; see
+ <a target="_blank" rel="nofollow noopener" href="https://github.blog/2019-08-16-highlights-from-git-2-23/">
+ https://github.blog/2019-08-16-highlights-from-git-2-23/</a>.
+ </blockquote>
+ </p>
+ <h2>GIT vs SVN</h2>
+
+ <p>Note in this table, that the various commands usually have many options (especially git)
+ which can change their behavior substantially. This table frequently is only showing
+ one of the main uses of the git commands. When in doubt, please google the command
+ (e.g. google <code>git branch</code>) to see all the other things a git command can do.</p>
+
+
+ <table class="downloads">
+ <tr>
+ <th>Goal / Task</th>
+ <th>SVN</th>
+ <th>Git/GitHub</th>
+ <th>Comments/Discussion/Comparisons</th>
+ </tr>
+ <tr>
+ <td>checkout</td>
+ <td>svn checkout <url-of-a-branch></td>
+ <td><p>git clone <repo-url>
+ </p>
+ <p>git clone <repo-url> -branch <branch-name>
+ </p>
+ </td>
+ <td><p>SVN checkout
+ <ol><li>making a working tree of the contents of some (usually remote) repository</li>
+ <li>updating an existing working tree to the "head" level of the repository, to
+ catch up with any changes made by others.</li>
+ </ol>
+ </p>
+ <p>Git has distributed repositories; to get a local working tree, you first need to have a local
+ clone of a (usually remote) repository.
+ The clone operation creates a full (all branches, tags, etc.) copy of the remote repository
+ onto the local machine.
+ Subsequently, the default branch (or a specific branch) is checked out into the working tree.
+ </p>
+ </td>
+
+ </tr>
+ <tr>
+ <td>update to current</td>
+ <td>svn update</td>
+ <td>git pull</td>
+ <td><p>Update makes the working tree have the same level as the remote.</p>
+ <p>SVN update may cause merging to occur, and merge conflicts which are resolved by hand.</p>
+ <p>git pull does this in a 2 step process:
+ <ul><li>In step 1 it does a <code> git fetch </code> which updates the part of the local git repo that
+ are tracking the remote, to matching the current data at the remote
+ (by default, it does this for all branches). </li>
+ <li>In step 2, it does a <code> git merge </code> which merges the remote-tracking branch(s) which changed with
+ any corresponding local branch(s).
+ This may result in merge conflicts which will need manual resolving.
+ If there are conflicting changes, then there are two options:
+ <ol><li>stash the changes, pull, then apply the stash, then resolve conflicts</li>
+ <li>commit the local changes, pull, resolve conflicts</li>
+ </ol>
+
+ </li></ul>
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>commit</td>
+ <td>svn commit</td>
+ <td><p>git commit</p>
+ <p>git push</p></td>
+ <td><p>SVN commit uploads changes from the working tree to the remote repo.
+ It fails if the remote repo's files are beyond the working-tree's checkout level;
+ in this case an svn update is needed first before the commit can be done.
+ <ul><li>The update may create merge conflicts which will need to be resolved before the commit can happen.</li></ul>
+ </p>
+
+ <p>
+ A git commit commits the (staged) changes in the working tree to the local repository branch.
+ <ul><li>Eclipse team plugin for git allows you to
+ stage any unstaged items before doing the commit.</li></ul>
+ </p>
+ <p>A <code>git push</code> transfer the changes from the local repository up to the
+ the remote one, provided that those changes can be done using fast-forward.
+ Otherwise, like SVN, this operation fails. Fix this the same way, by doing a git pull
+ and addressing any merge issues.</p>
+ <p>
+ The local repo can be configured to talk to any number of other local or remote repositories
+ to sync with them.
+ However, most of the time, it is only configured to sync with a single canonical remote repo,
+ e.g. on GitHub.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>tag</td>
+ <td>svn copy <url>/trunk <url>/tags/<tag-name></td>
+ <td>git tag <tag-name></td>
+ <td><p>Tags are first-class citizens in git and represent a state of the repository.
+ In SVN, tags are just another folder and a manifestation of a folder naming convention.
+ </p>
+ </td>
+
+ </tr>
+ <tr>
+ <td>branch</td>
+ <td>svn copy <url>/trunk <url>/branches/<branch-namel></td>
+ <td>git branch <branch-name></td>
+ <td>Creating a branch does not "switch" the current checkout to the branch. See switch.</td>
+ </tr>
+ <tr>
+ <td>switch</td>
+ <td>svn switch <url></td>
+ <td>git switch <branch></td>
+ <td><p>SVN switch updates the local working tree (or portions of it) to some remote repo spot.</p>
+ <p>git switch is at the granularity of a branch.
+ The working tree and the git "index" of to-be-committed things are updated to match the new branch.
+ The <code>switch</code> command is a refactoring of the git checkout command; see
+ <a target="_blank" rel="nofollow noopener" href="https://github.blog/2019-08-16-highlights-from-git-2-23/">
+ https://github.blog/2019-08-16-highlights-from-git-2-23/</a>.
+ </p>
+ <p>Switch updates the local checkout to a different branch, preserving any changes not yet checked (maybe showing conflict editor), and changing where a commit will go with the same SVN repo.
+ git switch replaces the checkout tree (except for untracked things) with the branch/tag/revision.
+ If this would lose data (because you have uncommitted changes), the checkout is not done (error msg).</p>
+ </td>
+ </tr>
+ <tr>
+ <td>relocate (when the URL of the remote repo has changed)</td>
+ <td>svn relocate <from-url> <to-url></td>
+ <td>git remote set-url origin <remote-url></td>
+ <td><p>The git remote set-url associates a remote with a name, such as origin, which
+ by convention is used by default for many operations involving remotes.</p></td>
+ </tr>
+ <tr>
+ <td>change the commit message</td>
+ <td>svn propset, eclipse: in team history view</td>
+ <td>git commit amend - changes the last commit message</td>
+ <td><p>In SVN, it is easy to update the properties (commit messages) of any past commit.
+ In git, this is possible but intentionally difficult.
+ The version history in git is covered by cryptographic hashes.
+ In order for the distributed version control to work well,
+ it is essential that the hashes are consistent across all clones of the repositories.
+ If they are not, manual intervention is necessary.
+ </p>
+ <p>
+ Rewriting the commit message is fine, as long as the commit is only to your private
+ local repo. But it will cause problems if it has been "published" (that is, pushed to a
+ remote repo, where others might have downloaded it). Because of this,
+ it is highly discouraged to re-write git histories and only possible using a "force push".
+ For this reason, shared branches such as the "master" branch or maintenance branches
+ are usually "protected", meaning that force-pushes are rejected.
+ But since it is not uncommon that things need to be rewritten,
+ it is usually accepted that people force-push changes into feature branches they work on.
+ But it should still be avoided, in particular if there are others
+ contributing to the same feature branch.</p></td>
+ </tr>
+ <tr>
+ <td>submitting a patch</td>
+ <td><p>Create a Jira issue</p>
+ <p>implement changes</p>
+ <p>svn diff</p>
+ <p>attach that diff to Jira issue</p>
+ </td>
+ <td><p>Create a Jira issue</p>
+ <p>
+ Create a branch following naming convention:<br/>
+ e.g. feature/UIMA-1234-cool-new-feature</p>
+ <p>commit any changes for the patch to that branch</p>
+ <p>push the branch to remote</p>
+ <p>create a pull request via GitHub site</p>
+ <p>wait for the CI (Continuous Integration) process to
+ finish any checking/testing of the pull request</p>
+ <p>ask for a review (if you are not a committer)</p>
+ <p>make changes (if needed) and repeat review</p>
+ <p>merge the pull request (or ask a committer to do it)</p>
+ </td>
+ <td>
+ <p>With the SVN-based infrastructure that is in place at te ASF, diffs need to be handled manually.
+ I.e. contributors need to create them,
+ committers need to apply them, review them, run test builds,
+ and the process repeats if changes need to be made.
+ </p>
+ <p>In GitHub contributions are made through pull requests;
+ these are required (vs just doing git push) when the branch being pushed to is
+ marked as "protected". By convention, the release branches and tags, and the "master" are
+ marked this way. This is changed/managed by filing a Jira issue with INFRA.
+ </p>
+ <p>While working on a feature or bug fix in a separate branch, simple pushes can be used.</p>
+ <p>
+ A pull request provides the ability to
+ discuss changes in pull requests, perform reviews, and run automated checks.
+ </p>
+ <p>The ASF Jenkins is already set up to automatically monitor pull requests
+ and to run automated checks on them. For security reasons,
+ pull requests from non-committers are not built automatically but must be triggered by a committer
+ by posting a comment such as "Jenkins, can you test this please."
+ to the discussion thread of the pull request on the GitHub website.
+ </p>
+ </td>
+ </tr>
+ </table>
+
+ </section>
+
+</body>
+</document>
\ No newline at end of file
Modified: uima/site/trunk/uima-website/xdocs/git.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/git.xml?rev=1866703&r1=1866702&r2=1866703&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/git.xml (original)
+++ uima/site/trunk/uima-website/xdocs/git.xml Mon Sep 9 17:51:10 2019
@@ -28,13 +28,20 @@ under the License.
<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">git-conventions</a> for information about the GIT conventions being used.</p>
+ href="git-conventions.html">git-conventions</a> for information about the GIT conventions being used.</p>
<h2>Converting a project to GIT</h2>
<p>See <a target="_blank" rel="noopener"
- href="convert-to-git">convert-to-git</a> for information on the steps to take to move / convert a project from SVN to GIT.</p>
+ 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>
</section>