xdocs/git-conventions.xml - uima-site - Git at Google

 <?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 Conventions for UIMA projects</title>
     <author email="dev@uima.apache.org"> Apache UIMA Documentation Team</author>
   </properties>

   <body>

     <section name="Git Conventions">

     <p>This describes various conventions and the reasons behind them, concerning use of GIT.</p>

     <h3>Branch naming</h3>

     <h4>master</h4>

       <p>This is the main branch where things are merged into, and from time to time, releases are made from.</p>
       <p>Some project may have multiple branches e.g., master and master-v2.
       These typically reflect on-going versions being developed together.</p>

     <h4>branches for working</h4>
       <p>Work is typically done in a branch.  This because the master(s) are protected, which means they cannot be "pushed" to,
         but rather, a change must be pulled from a branch via a pull request.</p>

          <p style="margin-left: 2rem">
          Exception: trivial changes, or changes not needing review.  These can be made on the master, which corresponds
          to how we worked in SVN.  Depending on the particular Repository protection scheme, committers may be able
          to push to the branch without 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> 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>

     <h4>Branches for releasing</h4>
       <p>
       When you are about to make a release, you typically will create a branch for the release; this branch
       will be checked out and the maven release prepare / perform will run on it, and in the process create
       commits to the branch updating the various "versions", first by removing the -SNAPSHOT, and then by updating them
       to the next SNAPSHOT version.
       </p>
       <p>The maven release prepare/perform operations include "pushing" to the remote.
       </p>
       <p>
       The branches used for the release work are typically named <code>rc/uimaXXXXX-x.y.z</code>.
        (rc stands for Release Candidate).
       See <a target="_blank" rel="nofollow noopener"
       href="git-release-notes.html">git-release-notes.hmtl</a>.
       </p>

     <h3>Commit messages</h3>

     <p>Example: <code>[UIMA-1234] summary-of-Jira  summary-of-change</code></p>

     <p>Git has a two-section commit message.  The first line should be a one-line id with summaries.
        Following that is an optional section of multiple lines that can have more 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>

     </section>

   </body>
 </document>
	<?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 Conventions for UIMA projects</title>
	<author email="dev@uima.apache.org"> Apache UIMA Documentation Team</author>
	</properties>

	<body>

	<section name="Git Conventions">

	<p>This describes various conventions and the reasons behind them, concerning use of GIT.</p>

	<h3>Branch naming</h3>

	<h4>master</h4>

	<p>This is the main branch where things are merged into, and from time to time, releases are made from.</p>
	<p>Some project may have multiple branches e.g., master and master-v2.
	These typically reflect on-going versions being developed together.</p>

	<h4>branches for working</h4>
	<p>Work is typically done in a branch. This because the master(s) are protected, which means they cannot be "pushed" to,
	but rather, a change must be pulled from a branch via a pull request.</p>

	<p style="margin-left: 2rem">
	Exception: trivial changes, or changes not needing review. These can be made on the master, which corresponds
	to how we worked in SVN. Depending on the particular Repository protection scheme, committers may be able
	to push to the branch without 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> 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>

	<h4>Branches for releasing</h4>
	<p>
	When you are about to make a release, you typically will create a branch for the release; this branch
	will be checked out and the maven release prepare / perform will run on it, and in the process create
	commits to the branch updating the various "versions", first by removing the -SNAPSHOT, and then by updating them
	to the next SNAPSHOT version.
	</p>
	<p>The maven release prepare/perform operations include "pushing" to the remote.
	</p>
	<p>
	The branches used for the release work are typically named <code>rc/uimaXXXXX-x.y.z</code>.
	(rc stands for Release Candidate).
	See <a target="_blank" rel="nofollow noopener"
	href="git-release-notes.html">git-release-notes.hmtl</a>.
	</p>

	<h3>Commit messages</h3>

	<p>Example: <code>[UIMA-1234] summary-of-Jira summary-of-change</code></p>

	<p>Git has a two-section commit message. The first line should be a one-line id with summaries.
	Following that is an optional section of multiple lines that can have more 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>

	</section>

	</body>
	</document>