Using GitHub and SourceTree to work with DITA TC repositories Kristen James Eberlein Eberlein Consulting LLC
Agenda 1. Before you begin 2. Getting set up: 1. Fork the DITA TC repository 2. Clone your fork to your local system 3. Add the upstream repository 4. Fetch from the upstream repository 3. Workflow for performing work 1. Create a new branch 2. Perform your work 3. Commit your changes 4. Push the commit to your fork 5. Open a pull request against the upstream repository 4. Best practices 1. Commits and commit messages 2. Best practices for pull requests and pull request messages
Before you begin Install SourceTree Create a GitHub account, if you don t already have one
Workflow for performing work 1. Create a new branch 2. Perform your work 3. Commit your changes 4. Push the commit to your fork 5. Open a pull request against the upstream repository
Fork the DITA TC repository 1. From the GitHub repository page, click Fork. 2. Make note of the URL for your fork; you will need it in the next procedure. Here are the current DITA TC repositories: DITA specification DITA for Technical Communication DITA for Learning & Training Lightweight DITA DITA stylesheets DITA RNG converter
Clone your forked repository to your local system 1. From within SourceTree, click File > Clone/New. 2. In the Clone window, specify information: 1. In the first field, paste the URL of your fork. 2. In the 2 nd field, type the path for the directory on your local system. 3. In the 3 rd field, type a name for the repository. This name will be displayed on the tab in SourceTree. 3. Click Clone.
Add the upstream repository 1. From within SourceTree, on the tab for the repository that you cloned, click Settings. 2. On the Repository Settings window, click Add. 3. On the Remote Details window, provide information: 1. In the Remote name field, type upstream. 2. In the URL/Path field, paste the URL of the repository that you forked. 3. Click OK. 4. On the Repository Settings window, click OK.
Fetch from the upstream repo 1. From Source, in the left pane, expand REMOTES. 2. Right-click upstream, and click Fetch from upstream. SourceTree will fetch the content and branches from the upstream repository.
Workflow for performing work 1. Create a new branch, based on the appropriate branch of the upstream repository. 2. Perform your work locally. 3. Commit your changes. 4. Push your changes to your fork of the upstream repository. 5. Open a pull request against the appropriate branch of the upstream repository.
Create a new branch on which to perform the work 1. Expand REMOTES > Upstream. 2. Right-click the appropriate upstream branch, and then click Checkout upstream/<name-ofbranch>. 3. In the Checkout window, in the New local branch name field, type a name for the new branch. 4. Click OK.
Committing your changes 1. In SourceTree, you can see that you have uncommitted changes. 2. On the File Status page, select the modified files that you want to commit and stage them. 3. In the text box, enter your commit message, and then click Commit.
Push your changes to your fork 1. Click Push. 2. On the Push window, select the branch that you were working on, and then click Push.
Open a pull request (1 of 2) 1. From a browser, go to your fork of the DITA repository. 2. Switch to the branch on which you were working. 3. Check that you see your recent commit, and then click New pull request.
Open a pull request (2 of 2) 1. On the Open a pull request window, provide the necessary information: 1. Change the base field to the upstream branch in which you want to integrate your changes. 2. Ensure that the compare field is set to the branch in which you performed your work. 3. By default, the title field is populated with the title of your commit. 4. In the window, add more information about what your pull request contains. 5. Click Create pull request. You can continue to make commits to a pull request until it is merged.
Best practices 1. Best practices 1. Commits and commit messages 2. Best practices for pull requests and pull request messages
Best practices for commits A commit should focus on a single item that can be easily described. It can involve one or 100 files, but the changes should make sense together. Good A commit that changes a group of topics to rework short descriptions A commit that updates a group of topics and adds some topics to implement a specific DITA 2.0 feature A commit that updates every topic on @keyref to enforce consistency Not good A commit that adds a topic, edits 3 topics for an unrelated feature, corrects a typo in a map A commit that removes @rev from 50 topics and adds several new examples
Best practices for commit messages A commit message should be short and clear. Anyone reading the commit message (and familiar with TC work) should know what has changed Good Reworked short description in base element topics Implement new spiffy publication map Fixed normative language for keyref resolution Not good Edited topics Changes
Best practices for pull requests A pull request should group together related commits. You can continue to make commits after you have opened the pull request. Pushing commits to the same branch automatically adds them to the pull request. Good A commit to implement the DITA 2.0 element reference template + a commit that improves examples in those topics Not good A commit that suggests new examples for conref resultion + a comment that fixes typos in an appendix
Best practices for pull request messages
Educational resources
Educational resources On-demand training from GitHub.com Get started with SourceTree Help topics about the following: Install and set up SourceTree Understand the interface Version control and SourceTree Work using Git Working with Mercurial