| <?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>Converting project to GIT</title> | |
| <author email="dev@uima.apache.org"> Apache UIMA Documentation Team</author> | |
| </properties> | |
| <body> | |
| <section name="Converting a project to GIT"> | |
| <p>This describes the various steps needed in converting a project from SVN to GIT.</p> | |
| <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> | |
| <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> | |
| <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 the connection: | |
| <p><code>scm:git:https://github.com/apache/...proj-name.../...subdir...</code></p> | |
| </li> | |
| <li>For the developerConnection: This must point to the entire repository (no subdirs) | |
| <p><code>scm:git:https://github.com/apache/...proj-name.../</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 other versions, e.g. uima-v2, replace <code>master</code> with <code>master-v2</code> (or the other version name)</p></li> | |
| </ul> | |
| <h3>Update the website docs to refer to the source at github.com/apache.</h3> | |
| </section> | |
| </body> | |
| </document> |