{"_id":"58a1eb7c76d9fb25004afc78","version":{"_id":"58a1eb7b76d9fb25004afc6d","project":"56835bb57af9120d007ac339","__v":1,"createdAt":"2017-02-13T17:23:07.814Z","releaseDate":"2017-02-13T17:23:07.814Z","categories":["58a1eb7b76d9fb25004afc6e","58a1eb7b76d9fb25004afc6f","58a1eb7b76d9fb25004afc70","58a1eb7b76d9fb25004afc71"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Artifice","version_clean":"20170213.0.0","version":"20170213"},"category":{"_id":"58a1eb7b76d9fb25004afc70","__v":0,"version":"58a1eb7b76d9fb25004afc6d","project":"56835bb57af9120d007ac339","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-05T04:02:31.286Z","from_sync":false,"order":2,"slug":"development-setup","title":"Development and Test"},"parentDoc":null,"project":"56835bb57af9120d007ac339","__v":0,"user":"56835b733b87430d00483b77","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-05T15:49:22.059Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"Git is an extremely powerful distributed version control system that helps dRonin developers coordinate their work.  While there's a bit of a learning curve to begin using Git, it's well worth it.\n\nThe individual Development Setup documentation pages (available for [Mac](doc:development-setup-os-x), [Windows](doc:development-setup-windows), and  [Linux](doc:development-setup-linux)) document installing git and associated development tools.  This page instead covers best practices for how to maintain your git repository. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Concept: forks\",\n  \"body\": \"Every developer (and many users) has their own fork (copy) of the dRonin code repository with its own history.  In this fork, changes can be made until they are \\\"ready\\\", when they can be submitted to the main dRonin fork as a pull request.  When dRonin accepts this pull request, the history associated with those changes is appended to the dRonin revision control history.\"\n}\n[/block]\nIt may also be helpful to run through the [tryGit tutorial](https://try.github.io/levels/1/challenges/1) to become familiar with the git command line tools.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Obtaining your own fork of the GitHub repository\"\n}\n[/block]\n* [Create an account on GitHub](https://github.com/signup/free).\n* Go to the [dRonin GitHub page](https://github.com/d-ronin/dronin).\n* Click the fork button:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/HjUJwe3dTBKhp96B926D_fork.png\",\n        \"fork.png\",\n        \"900\",\n        \"119\",\n        \"#ed673e\",\n        \"\"\n      ],\n      \"caption\": \"Github Project Page: Fork\"\n    }\n  ]\n}\n[/block]\nYou will be taken to your fork's page.  At the top, there will be an URL for your fork, in the format `https://github.com/yourusername/dRonin.git` – note this URL.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"If you already have cloned from the main project... (not your fork)\",\n  \"body\": \"Then you already have a clone, and you need to adjust your \\\"origin\\\" remote to point to your fork.\\n\\nInstead of the following two steps, do this:\\n```\\ncd dRonin\\ngit remote add upstream https://github.com/d-ronin/dRonin.git\\ngit fetch upstream\\ngit remote remove origin\\ngit remote add origin https://github.com/yourusername/dRonin.git\\ngit fetch origin\\n```\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Clone your fork locally\"\n}\n[/block]\nFollow the instructions for the development setup linked above, but when you clone the repository, provide your fork's URL:\n\n```\ngit clone https://github.com/yourusername/dRonin.git\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Add a remote for the main (upstream) dRonin project\"\n}\n[/block]\nAfter you create and clone your own fork, it is helpful to be able to access the primary project repository as well.  To do this, execute the following commands:\n\n```\ngit remote add upstream https://github.com/d-ronin/dronin.git\ngit fetch upstream\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting the latest next\"\n}\n[/block]\nYour local fork just contains a snapshot of the origin (your fork) and upstream repositories.  Later, to update it, just run these commands:\n\n```\ngit fetch upstream\ngit checkout upstream/next\n```\n\nThe first command (fetch) downloads all changes that have happened since last fetch; it does not change your working copy at all.  `git checkout upstream/next` replaces your working copy with the current code from `next`, dRonin's development branch.\n\nYou should usually clean the build environment after updating or changing branches:\n\n```\nmake all_clean\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Retrieving and testing other pull requests\"\n}\n[/block]\nIt is also helpful to be able to retrieve and test other peoples' pull requests.  There is a neat trick to make retrieving PRs easier from github.  First, from your dronin repository edit `.git/config`.  In the `[remote \"upstream\"]` section, add a new line that says:\n\n```\n        fetch = +refs/pull/*/head:refs/remotes/pr/*\n```\n\nAfter this, you can run a series of commands like:\n\n```\ngit fetch upstream\ngit checkout upstream/next\ngit merge pr/1000\ngit merge pr/1100\n```\n\nto get source code of next with PR's 1000 and 1100 applied for testing.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Set your user information\"\n}\n[/block]\nGit needs to know who you are so it can properly attribute your changes-- it won't let you commit until it's configured.  So go ahead and tell it:\n\n```\ngit config --global user.name \"Your Name\"\ngit config --global user.email \"you:::at:::example.com\"\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Beginning a new feature branch\"\n}\n[/block]\nIf you've spotted a bug, want to adjust some text in the project to be clearer, or are looking to add a new feature: Thank you!  Here's how it works.\n\nFirst, get the current development code, and clean your build environment:\n\n```\ngit checkout upstream/next\nmake all_clean\n```\n\nNext, name your branch and begin your work:\n\n```\ngit checkout -b myNiceBranch\n```\n\nThis takes a virtual copy of the current branch (which should be current `next`), names it `myNiceBranch`, and checks it out into your `dRonin` directory.\n\nYou can now edit the source code files and make test builds.  For each logical work item within the branch, you can add the files you want to commit (whether they're new or just have changes) and then commit them:\n\n```\ngit add flight/targets/cc4d/fw/mycoolcode.c Makefile\ngit commit\n```\n\nYou'll be asked to type in a commit message.  The first line is expected to be a short subject line that indicates the subsystem of the code and is 50 characters or less; subsequent lines can describe the changes in greater detail:\n\n```\nflight: add support for the CC4D flight controller\n\nmycoolcode is also added.  We're no longer confined to just three spatial dimensions.  \nFixes bug #123.\n```\n\nAfter this commit, you can continue working and producing additional change sets on this branch.\n\nWhen the work is all done, you can run `git push` to send the contents of `myNiceBranch` to your fork on GitHub, and then visit your GitHub page to open a pull request for our review.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Advanced topics, not yet covered\",\n  \"body\": \"Sometimes it's necessary to rebase, in order to get a clean revision history or to pick up changes from upstream.\\n\\nFor now, a brief tutorial on rebasing is here: http://rypress.com/tutorials/git/rebasing\"\n}\n[/block]","excerpt":"Best practices when following and contributing to the dRonin repository","slug":"tracking-development-with-git","type":"basic","title":"Tracking Development with Git"}

Tracking Development with Git

Best practices when following and contributing to the dRonin repository

Git is an extremely powerful distributed version control system that helps dRonin developers coordinate their work. While there's a bit of a learning curve to begin using Git, it's well worth it. The individual Development Setup documentation pages (available for [Mac](doc:development-setup-os-x), [Windows](doc:development-setup-windows), and [Linux](doc:development-setup-linux)) document installing git and associated development tools. This page instead covers best practices for how to maintain your git repository. [block:callout] { "type": "info", "title": "Concept: forks", "body": "Every developer (and many users) has their own fork (copy) of the dRonin code repository with its own history. In this fork, changes can be made until they are \"ready\", when they can be submitted to the main dRonin fork as a pull request. When dRonin accepts this pull request, the history associated with those changes is appended to the dRonin revision control history." } [/block] It may also be helpful to run through the [tryGit tutorial](https://try.github.io/levels/1/challenges/1) to become familiar with the git command line tools. [block:api-header] { "type": "basic", "title": "Obtaining your own fork of the GitHub repository" } [/block] * [Create an account on GitHub](https://github.com/signup/free). * Go to the [dRonin GitHub page](https://github.com/d-ronin/dronin). * Click the fork button: [block:image] { "images": [ { "image": [ "https://files.readme.io/HjUJwe3dTBKhp96B926D_fork.png", "fork.png", "900", "119", "#ed673e", "" ], "caption": "Github Project Page: Fork" } ] } [/block] You will be taken to your fork's page. At the top, there will be an URL for your fork, in the format `https://github.com/yourusername/dRonin.git` – note this URL. [block:callout] { "type": "warning", "title": "If you already have cloned from the main project... (not your fork)", "body": "Then you already have a clone, and you need to adjust your \"origin\" remote to point to your fork.\n\nInstead of the following two steps, do this:\n```\ncd dRonin\ngit remote add upstream https://github.com/d-ronin/dRonin.git\ngit fetch upstream\ngit remote remove origin\ngit remote add origin https://github.com/yourusername/dRonin.git\ngit fetch origin\n```" } [/block] [block:api-header] { "type": "basic", "title": "Clone your fork locally" } [/block] Follow the instructions for the development setup linked above, but when you clone the repository, provide your fork's URL: ``` git clone https://github.com/yourusername/dRonin.git ``` [block:api-header] { "type": "basic", "title": "Add a remote for the main (upstream) dRonin project" } [/block] After you create and clone your own fork, it is helpful to be able to access the primary project repository as well. To do this, execute the following commands: ``` git remote add upstream https://github.com/d-ronin/dronin.git git fetch upstream ``` [block:api-header] { "type": "basic", "title": "Getting the latest next" } [/block] Your local fork just contains a snapshot of the origin (your fork) and upstream repositories. Later, to update it, just run these commands: ``` git fetch upstream git checkout upstream/next ``` The first command (fetch) downloads all changes that have happened since last fetch; it does not change your working copy at all. `git checkout upstream/next` replaces your working copy with the current code from `next`, dRonin's development branch. You should usually clean the build environment after updating or changing branches: ``` make all_clean ``` [block:api-header] { "type": "basic", "title": "Retrieving and testing other pull requests" } [/block] It is also helpful to be able to retrieve and test other peoples' pull requests. There is a neat trick to make retrieving PRs easier from github. First, from your dronin repository edit `.git/config`. In the `[remote "upstream"]` section, add a new line that says: ``` fetch = +refs/pull/*/head:refs/remotes/pr/* ``` After this, you can run a series of commands like: ``` git fetch upstream git checkout upstream/next git merge pr/1000 git merge pr/1100 ``` to get source code of next with PR's 1000 and 1100 applied for testing. [block:api-header] { "type": "basic", "title": "Set your user information" } [/block] Git needs to know who you are so it can properly attribute your changes-- it won't let you commit until it's configured. So go ahead and tell it: ``` git config --global user.name "Your Name" git config --global user.email "you@example.com" ``` [block:api-header] { "type": "basic", "title": "Beginning a new feature branch" } [/block] If you've spotted a bug, want to adjust some text in the project to be clearer, or are looking to add a new feature: Thank you! Here's how it works. First, get the current development code, and clean your build environment: ``` git checkout upstream/next make all_clean ``` Next, name your branch and begin your work: ``` git checkout -b myNiceBranch ``` This takes a virtual copy of the current branch (which should be current `next`), names it `myNiceBranch`, and checks it out into your `dRonin` directory. You can now edit the source code files and make test builds. For each logical work item within the branch, you can add the files you want to commit (whether they're new or just have changes) and then commit them: ``` git add flight/targets/cc4d/fw/mycoolcode.c Makefile git commit ``` You'll be asked to type in a commit message. The first line is expected to be a short subject line that indicates the subsystem of the code and is 50 characters or less; subsequent lines can describe the changes in greater detail: ``` flight: add support for the CC4D flight controller mycoolcode is also added. We're no longer confined to just three spatial dimensions. Fixes bug #123. ``` After this commit, you can continue working and producing additional change sets on this branch. When the work is all done, you can run `git push` to send the contents of `myNiceBranch` to your fork on GitHub, and then visit your GitHub page to open a pull request for our review. [block:callout] { "type": "warning", "title": "Advanced topics, not yet covered", "body": "Sometimes it's necessary to rebase, in order to get a clean revision history or to pick up changes from upstream.\n\nFor now, a brief tutorial on rebasing is here: http://rypress.com/tutorials/git/rebasing" } [/block]