https://wiki.diasporafoundation.org/api.php?action=feedcontributions&user=Cocoa&feedformat=atomdiaspora* project wiki - User contributions [en]2024-03-29T01:19:50ZUser contributionsMediaWiki 1.39.3https://wiki.diasporafoundation.org/wiki/index.php?title=Git_workflow&diff=337Git workflow2012-12-01T16:11:19Z<p>Cocoa: /* Step-by-step (the short version) */</p>
<hr />
<div>If you’re a developer who wants to work on the Diaspora source code and submit your changes for consideration to be merged into core Diaspora* code, here’s how. Thanks to [https://github.com/ginatrapani/ThinkUp ThinkUp] for their awesome developer guide, which inspired ours.<br />
<br />
= Branching model =<br />
<br />
Firstly the most important part, the branching model that Diaspora follows. Our branching model is based on [http://nvie.com/posts/a-successful-git-branching-model/ a post on Git branching models] by [http://nvie.com/about/ nvie].<br />
<br />
In short, the model is explained nicely in this picture: [[Image:http://nvie.com/img/2009/12/Screen-shot-2009-12-24-at-11.32.03.png|nvie git branching model]]<br />
<br />
To make following this model easier we use [https://github.com/nvie/gitflow git-flow] which contains high level extensions for this Git branching model. Please start by [https://github.com/nvie/gitflow/wiki/Installation installing the git-flow extensions] as per installation instructions on their project page. There is also [http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/ a blog post] explaining in short how git-flow basics work.<br />
<br />
Please note that the usage of git-flow extensions for Diaspora* does not stop the usage of vanilla git commands! If you are not able to use git-flow or do not feel comfortable with using it, please feel free to use normal git commands. But we do enforce the branching model so please read the branching model post carefully and follow the guidelines closely.<br />
<br />
Discussion on improving this branching model happens on [http://loom.io/discussions/628 Loom.io].<br />
<br />
= Quickfire Do’s and Don’t’s =<br />
<br />
If you’re familiar with git and GitHub, here’s the short version of what you need to know. Once you fork and clone the Diaspora code:<br />
<br />
* '''Never, ever, do anything in master branch. The branch develop is the head of development, master is for stable releases!'''<br />
* '''Don’t develop on the develop branch.''' Always create a feature branch specific to [https://github.com/diaspora/diaspora/issues the issue] you’re working on. Name it by issue # and description. For example, if you’re working on Issue #359, an aspect naming fix, your feature branch should be called 359-aspect-names. If you decide to work on another issue mid-stream, create a new branch for that issue–don’t work on both in one branch.<br />
* '''Do not merge''' the upstream develop with your feature branch; '''rebase''' your branch on top of the upstream develop.<br />
* '''A single feature branch should represent changes related to a single issue.''' If you decide to work on another issue, create another feature branch from develop.<br />
<br />
= Step-by-step (the short version) =<br />
<br />
# Fork on GitHub (click Fork button)<br />
# Clone to computer (<tt>$ git clone git@github.com:you/diaspora.git</tt>)<br />
# Don’t forget to cd into your repo: (<tt>$ cd diaspora/</tt>)<br />
# Set up remote upstream (<tt>$ git remote add upstream git://github.com/diaspora/diaspora.git</tt>)<br />
# If you use git-flow initialize it: <tt>git checkout master &amp;&amp; git flow init -d &amp;&amp; git checkout develop</tt><br />
# Start working on a new issue or feature (<tt>$ git flow feature start 100-description</tt>, naming convention is ''issuenumber-description'', if you don’t have a bug report no worries just skip the number)<br />
# Develop on feature. (<tt>$ git add . ; git commit -m 'commit message'</tt>)<br />
# Push branch to GitHub (<tt>$ git flow feature publish 100-description</tt> or simply <tt>git push -f</tt>, just to stop you losing local changes on the event of hardware failure)<br />
# Fetch upstream (<tt>$ git fetch upstream</tt>)<br />
# Update local develop (<tt>$ git checkout develop; git pull upstream develop</tt>)<br />
# Switch back to feature (<tt>$ git flow feature checkout 100-new-feature ; git rebase develop</tt>)<br />
# Repeat steps 6-9 till dev is complete<br />
# edit Changelog.md adding a line describing your change in the appropriate section<br />
# Rebase develop in to feature branch (<tt>$ git rebase develop feature/100-description</tt>)<br />
# Publish feature branch to Github (<tt>$ git flow feature publish 100-description</tt>)<br />
# Issue pull request for develop branch (Click Pull Request button)<br />
<br />
Note! Do not do <tt>git flow feature finish</tt> for your branch. Submit the whole feature branch as a pull request instead without finishing it. It will be merged to ''develop'' by a reviewer.<br />
<br />
= Step-by-step (the long version) =<br />
<br />
If you’re new to git and GitHub, here’s the longer version of these instructions.<br />
<br />
== Install git and git-flow ==<br />
<br />
# [http://git-scm.com/downloads Install Git for your platform]<br />
# [https://github.com/nvie/gitflow/wiki/Installation Install git-flow extensions] IF available for your platform<br />
# (Optional but highly recommended) [https://github.com/bobthecow/git-flow-completion Install git-flow completion] for some bash auto-complete magic<br />
<br />
== Create an account on GitHub and fork the Diaspora repository. ==<br />
<br />
# Create a free account on GitHub, and log in.<br />
# Go to [http://github.com/diaspora/diaspora the main Diaspora page on GitHub].<br />
# Click the “Fork” button near the top of the screen. This will get you your own copy that you can make changes to. [[Image:http://img.skitch.com/20101018-j5xmmrs6ccn9ku2gic12y13cf9.png]]<br />
<br />
== Establish connectivity between your GitHub account and your development machine. ==<br />
<br />
# Generate an SSH key on your development machine. Here’s a “good guide”:http://help.github.com/key-setup-redirect that gives you specific directions for whatever OS you’re accessing the page with.<br />
# Make sure you’ve got an SSH public key on your machine and recorded in your GitHub account. You can see your SSH Public Keys on the Account Overview section of your GitHub account. [[Image:http://img.skitch.com/20101018-nayqmm1ne8qdyafpjb7tib4fi4.png]]<br />
# To test the GitHub authentication run:<br />
<br />
<pre>$ ssh git@github.com</pre><br />
If all is well, you should see something like this:<br />
<br />
<pre>PTY allocation request failed on channel 0<br />
ERROR: Hi username! You've successfully authenticated, but GitHub does not provide shell access<br />
Connection to github.com closed.</pre><br />
<br />
<br />
== Clone your GitHub fork to your development machine ==<br />
<br />
Run a clone command against your GitHub fork. It will look something like this except that it will use your GitHub account name instead of “you”:<br />
<br />
<pre>$ git clone git@github.com:you/diaspora.git </pre><br />
That downloads your copy of Diaspora to a git repository on your development machine. Change directory into the new diaspora directory.<br />
<br />
Check that you have [https://github.com/nvie/gitflow git-flow] installed and run<br />
<br />
<pre>$ git checkout master<br />
$ git flow init -d <br />
$ git checkout develop</pre><br />
Now you need to install everything you need to run it - which is quite a lot of stuff. We have a guide to [http://github.com/diaspora/diaspora/wiki/Installing-and-Running-Diaspora installing and running Diaspora] which should help. Pop into #diaspora on IRC (freenode) if you have problems.<br />
<br />
You’ll know you’re done when you can run specs (in two stages - the cucumber features, which are selenium acceptance tests, and the rspec tests, which are unit tests) by doing this:<br />
<br />
<pre>$ rake spec</pre><br />
'''We try to make sure these always succeed.''' Our [http://ci.joindiaspora.com continuous integration server] will tell you if there any current failures. If you have any test failures that you don’t see on CI, come ask in the #diaspora-dev IRC channel.<br />
<br />
== Figure out what to work on ==<br />
<br />
Maybe you have a feature addition in mind, but if not, check out our [https://github.com/diaspora/diaspora/issues issue tracker], or come ask in IRC what needs doing.<br />
<br />
== Create an Issue-Specific Feature Branch ==<br />
<br />
Before you start working on a new feature or bugfix, create a new feature branch in your local repository that’s dedicated to that one change. Name it by issue number (if applicable, if there’s no issue just skip it) and description. For example, if you’re working on issue #359, a aspect naming bugfix, create a new branch called 359-aspect-names, like this:<br />
<br />
<pre>$ git flow feature start 359-aspect-names</pre><br />
== Write awesome code ==<br />
<br />
You must write unit tests for all bug fixes, no matter how small. We can help you!<br />
<br />
Edit and test the files on your development machine. When you’ve got something the way you want and established that it works, commit the changes to your branch on your development server’s git repo.<br />
<br />
<pre>$ git add &lt;filename&gt;<br />
$ git commit -m 'Issue #359: Some kind of descriptive message' </pre><br />
You’ll need to use git add for each file that you created or modified. There are ways to add multiple files, but I highly recommend a more deliberate approach unless you know what you’re doing.<br />
<br />
Then, you can push your new branch to GitHub, like this (replace 359-aspect-names with your branch name):<br />
<br />
<pre>$ git flow feature publish 359-aspect-names</pre><br />
You should be able to log into your GitHub account, switch to the branch, and see that your changes have been committed. Then click the Pull button to request that your commits get merged into the Diaspora development trunk. This command may not work after the first run, if so you can just use :<br />
<pre>$ git push -f</pre><br />
instead<br />
<br />
== Keep Your Repository Up to Date ==<br />
<br />
In order to get the latest updates from the development trunk do a one-time setup to establish the main GitHub repo as a remote by entering:<br />
<br />
<pre>$ git remote add upstream git://github.com/diaspora/diaspora.git</pre><br />
Verify you’ve now got “origin” and “upstream” remotes by entering:<br />
<br />
<pre>$ git remote</pre><br />
You’ll see upstream listed there.<br />
<br />
== Rebase Your Development Branch on the Latest Upstream ==<br />
<br />
To keep your development branch up to date, rebase your changes on top of the current state of the upstream master. Check out ''[[#gitrebase1|What’s git-rebase?]]'' below to learn more about rebasing.<br />
<br />
If you’ve set up an upstream branch as detailed above, and a development branch called 100-retweet-bugfix, you’d update upstream, update your local master, and rebase your branch from it like so:<br />
<br />
<tt>$ git fetch upstream $ git checkout develop $ git pull upstream develop $ git flow feature checkout 100-retweet-bugfix [make sure all is committed as necessary in branch] $ git rebase develop</tt> You may need to resolve conflicts that occur when a file on the development trunk and one of your files have both been changed. Edit each file to resolve the differences, then commit the fixes to your development server repo and test. Each file will need to be “added” before running a “commit.”<br />
<br />
<pre>$ git add &lt;filename&gt;<br />
$ git commit </pre><br />
To push the updates to your GitHub repo, replace 100-retweet-bugfix with your branch name and run:<br />
<br />
<pre>$ git flow feature publish 100-retweet-bugfix</pre><br />
== Send Diaspora a pull request on GitHub ==<br />
<br />
Github will notify us and we’ll review your patch and either pull it in or comment on it<br />
<br />
Helpful hint: You can always edit your last commit message by using:<br />
<br />
<pre>$ git commit --amend</pre><br />
== Some gotchas ==<br />
<br />
'''''Be careful not to commit any of your configuration files, logs, or throwaway test files to your GitHub repo.''''' These files can contain information you wouldn’t want publicly viewable and they will make it impossible to merge your contributions into the main development trunk of Diaspora.<br />
<br />
Most of these special files are listed in the ''.gitignore'' file and won’t be included in any commit, but you should carefully review the files you have modified and added before staging them and committing them to your repo. The git status command will display detailed information about any new files, modifications and staged.<br />
<br />
<pre>$ git status </pre><br />
'''''One thing you may not want to do is to issue a git commit with the -a option. This automatically stages and commits every modified file that’s not expressly defined in .gitignore, including your crawler logs.'''''<br />
<br />
<pre>$ git commit -a </pre><br />
<br />
<br />
== What’s git-rebase? ==<br />
<br />
Using <tt>git-rebase</tt> helps create clean commit trees and makes keeping your code up-to-date with the current state of upstream easy. Here’s how it works.<br />
<br />
Let’s say you’re working on Issue #212 a new plugin in your own branch and you start with something like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B #develop</pre><br />
You keep coding for a few days and then pull the latest upstream stuff and you end up like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B--C--D--E--F #develop</pre><br />
So all these new things (C,D,..F) have happened since you started. Normally you would just keep going (let’s say you’re not finished with the plugin yet) and then deal with a merge later on, which becomes a commit, which get moved upstream and ends up grafted on the tree forever.<br />
<br />
A cleaner way to do this is to use rebase to essentially rewrite your commits as if you had started at point F instead of point B. So just do:<br />
<br />
<pre>git rebase develop 212-my-new-plugin</pre><br />
git will rewrite your commits like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B--C--D--E--F #develop</pre><br />
It’s as if you had just started your branch. One immediate advantage you get is that you can test your branch now to see if C, D, E, or F had any impact on your code (you don’t need to wait until you’re finished with your plugin and merge to find this out). And, since you can keep doing this over and over again as you develop your plugin, at the end your merge will just be a fast-forward (in other words no merge at all).<br />
<br />
So when you’re ready to send the new plugin upstream, you do one last rebase, test, and then merge (which is really no merge at all) and send out your pull request. Then in most cases, a reviewer has a simple fast forward on her end (or at worst a very small rebase or merge) and over time that adds up to a simpler tree.<br />
<br />
More info on the git man page here: [http://schacon.github.com/git/git-rebase.html Git rebase: man page]<br />
<br />
[[Category:Developers]]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=Git_workflow&diff=336Git workflow2012-12-01T16:09:48Z<p>Cocoa: /* Write awesome code */</p>
<hr />
<div>If you’re a developer who wants to work on the Diaspora source code and submit your changes for consideration to be merged into core Diaspora* code, here’s how. Thanks to [https://github.com/ginatrapani/ThinkUp ThinkUp] for their awesome developer guide, which inspired ours.<br />
<br />
= Branching model =<br />
<br />
Firstly the most important part, the branching model that Diaspora follows. Our branching model is based on [http://nvie.com/posts/a-successful-git-branching-model/ a post on Git branching models] by [http://nvie.com/about/ nvie].<br />
<br />
In short, the model is explained nicely in this picture: [[Image:http://nvie.com/img/2009/12/Screen-shot-2009-12-24-at-11.32.03.png|nvie git branching model]]<br />
<br />
To make following this model easier we use [https://github.com/nvie/gitflow git-flow] which contains high level extensions for this Git branching model. Please start by [https://github.com/nvie/gitflow/wiki/Installation installing the git-flow extensions] as per installation instructions on their project page. There is also [http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/ a blog post] explaining in short how git-flow basics work.<br />
<br />
Please note that the usage of git-flow extensions for Diaspora* does not stop the usage of vanilla git commands! If you are not able to use git-flow or do not feel comfortable with using it, please feel free to use normal git commands. But we do enforce the branching model so please read the branching model post carefully and follow the guidelines closely.<br />
<br />
Discussion on improving this branching model happens on [http://loom.io/discussions/628 Loom.io].<br />
<br />
= Quickfire Do’s and Don’t’s =<br />
<br />
If you’re familiar with git and GitHub, here’s the short version of what you need to know. Once you fork and clone the Diaspora code:<br />
<br />
* '''Never, ever, do anything in master branch. The branch develop is the head of development, master is for stable releases!'''<br />
* '''Don’t develop on the develop branch.''' Always create a feature branch specific to [https://github.com/diaspora/diaspora/issues the issue] you’re working on. Name it by issue # and description. For example, if you’re working on Issue #359, an aspect naming fix, your feature branch should be called 359-aspect-names. If you decide to work on another issue mid-stream, create a new branch for that issue–don’t work on both in one branch.<br />
* '''Do not merge''' the upstream develop with your feature branch; '''rebase''' your branch on top of the upstream develop.<br />
* '''A single feature branch should represent changes related to a single issue.''' If you decide to work on another issue, create another feature branch from develop.<br />
<br />
= Step-by-step (the short version) =<br />
<br />
# Fork on GitHub (click Fork button)<br />
# Clone to computer (<tt>$ git clone git@github.com:you/diaspora.git</tt>)<br />
# Don’t forget to cd into your repo: (<tt>$ cd diaspora/</tt>)<br />
# Set up remote upstream (<tt>$ git remote add upstream git://github.com/diaspora/diaspora.git</tt>)<br />
# If you use git-flow initialize it: <tt>git checkout master &amp;&amp; git flow init -d &amp;&amp; git checkout develop</tt><br />
# Start working on a new issue or feature (<tt>$ git flow feature start 100-description</tt>, naming convention is ''issuenumber-description'', if you don’t have a bug report no worries just skip the number)<br />
# Develop on feature. (<tt>$ git add . ; git commit -m 'commit message'</tt>)<br />
# Push branch to GitHub (<tt>$ git flow feature publish 100-description</tt> or simply <tt>git push -f</tt>, just to stop you losing local changes on the event of hardware failure)<br />
# Fetch upstream (<tt>$ git fetch upstream</tt>)<br />
# Update local develop (<tt>$ git checkout develop; git pull upstream develop</tt>)<br />
# Switch back to feature (<tt>$ git flow feature checkout 100-new-feature ; git rebase develop</tt>)<br />
# Repeat steps 6-9 till dev is complete<br />
# Rebase develop in to feature branch (<tt>$ git rebase develop feature/100-description</tt>)<br />
# Publish feature branch to Github (<tt>$ git flow feature publish 100-description</tt>)<br />
# Issue pull request for develop branch (Click Pull Request button)<br />
<br />
Note! Do not do <tt>git flow feature finish</tt> for your branch. Submit the whole feature branch as a pull request instead without finishing it. It will be merged to ''develop'' by a reviewer.<br />
<br />
= Step-by-step (the long version) =<br />
<br />
If you’re new to git and GitHub, here’s the longer version of these instructions.<br />
<br />
== Install git and git-flow ==<br />
<br />
# [http://git-scm.com/downloads Install Git for your platform]<br />
# [https://github.com/nvie/gitflow/wiki/Installation Install git-flow extensions] IF available for your platform<br />
# (Optional but highly recommended) [https://github.com/bobthecow/git-flow-completion Install git-flow completion] for some bash auto-complete magic<br />
<br />
== Create an account on GitHub and fork the Diaspora repository. ==<br />
<br />
# Create a free account on GitHub, and log in.<br />
# Go to [http://github.com/diaspora/diaspora the main Diaspora page on GitHub].<br />
# Click the “Fork” button near the top of the screen. This will get you your own copy that you can make changes to. [[Image:http://img.skitch.com/20101018-j5xmmrs6ccn9ku2gic12y13cf9.png]]<br />
<br />
== Establish connectivity between your GitHub account and your development machine. ==<br />
<br />
# Generate an SSH key on your development machine. Here’s a “good guide”:http://help.github.com/key-setup-redirect that gives you specific directions for whatever OS you’re accessing the page with.<br />
# Make sure you’ve got an SSH public key on your machine and recorded in your GitHub account. You can see your SSH Public Keys on the Account Overview section of your GitHub account. [[Image:http://img.skitch.com/20101018-nayqmm1ne8qdyafpjb7tib4fi4.png]]<br />
# To test the GitHub authentication run:<br />
<br />
<pre>$ ssh git@github.com</pre><br />
If all is well, you should see something like this:<br />
<br />
<pre>PTY allocation request failed on channel 0<br />
ERROR: Hi username! You've successfully authenticated, but GitHub does not provide shell access<br />
Connection to github.com closed.</pre><br />
<br />
<br />
== Clone your GitHub fork to your development machine ==<br />
<br />
Run a clone command against your GitHub fork. It will look something like this except that it will use your GitHub account name instead of “you”:<br />
<br />
<pre>$ git clone git@github.com:you/diaspora.git </pre><br />
That downloads your copy of Diaspora to a git repository on your development machine. Change directory into the new diaspora directory.<br />
<br />
Check that you have [https://github.com/nvie/gitflow git-flow] installed and run<br />
<br />
<pre>$ git checkout master<br />
$ git flow init -d <br />
$ git checkout develop</pre><br />
Now you need to install everything you need to run it - which is quite a lot of stuff. We have a guide to [http://github.com/diaspora/diaspora/wiki/Installing-and-Running-Diaspora installing and running Diaspora] which should help. Pop into #diaspora on IRC (freenode) if you have problems.<br />
<br />
You’ll know you’re done when you can run specs (in two stages - the cucumber features, which are selenium acceptance tests, and the rspec tests, which are unit tests) by doing this:<br />
<br />
<pre>$ rake spec</pre><br />
'''We try to make sure these always succeed.''' Our [http://ci.joindiaspora.com continuous integration server] will tell you if there any current failures. If you have any test failures that you don’t see on CI, come ask in the #diaspora-dev IRC channel.<br />
<br />
== Figure out what to work on ==<br />
<br />
Maybe you have a feature addition in mind, but if not, check out our [https://github.com/diaspora/diaspora/issues issue tracker], or come ask in IRC what needs doing.<br />
<br />
== Create an Issue-Specific Feature Branch ==<br />
<br />
Before you start working on a new feature or bugfix, create a new feature branch in your local repository that’s dedicated to that one change. Name it by issue number (if applicable, if there’s no issue just skip it) and description. For example, if you’re working on issue #359, a aspect naming bugfix, create a new branch called 359-aspect-names, like this:<br />
<br />
<pre>$ git flow feature start 359-aspect-names</pre><br />
== Write awesome code ==<br />
<br />
You must write unit tests for all bug fixes, no matter how small. We can help you!<br />
<br />
Edit and test the files on your development machine. When you’ve got something the way you want and established that it works, commit the changes to your branch on your development server’s git repo.<br />
<br />
<pre>$ git add &lt;filename&gt;<br />
$ git commit -m 'Issue #359: Some kind of descriptive message' </pre><br />
You’ll need to use git add for each file that you created or modified. There are ways to add multiple files, but I highly recommend a more deliberate approach unless you know what you’re doing.<br />
<br />
Then, you can push your new branch to GitHub, like this (replace 359-aspect-names with your branch name):<br />
<br />
<pre>$ git flow feature publish 359-aspect-names</pre><br />
You should be able to log into your GitHub account, switch to the branch, and see that your changes have been committed. Then click the Pull button to request that your commits get merged into the Diaspora development trunk. This command may not work after the first run, if so you can just use :<br />
<pre>$ git push -f</pre><br />
instead<br />
<br />
== Keep Your Repository Up to Date ==<br />
<br />
In order to get the latest updates from the development trunk do a one-time setup to establish the main GitHub repo as a remote by entering:<br />
<br />
<pre>$ git remote add upstream git://github.com/diaspora/diaspora.git</pre><br />
Verify you’ve now got “origin” and “upstream” remotes by entering:<br />
<br />
<pre>$ git remote</pre><br />
You’ll see upstream listed there.<br />
<br />
== Rebase Your Development Branch on the Latest Upstream ==<br />
<br />
To keep your development branch up to date, rebase your changes on top of the current state of the upstream master. Check out ''[[#gitrebase1|What’s git-rebase?]]'' below to learn more about rebasing.<br />
<br />
If you’ve set up an upstream branch as detailed above, and a development branch called 100-retweet-bugfix, you’d update upstream, update your local master, and rebase your branch from it like so:<br />
<br />
<tt>$ git fetch upstream $ git checkout develop $ git pull upstream develop $ git flow feature checkout 100-retweet-bugfix [make sure all is committed as necessary in branch] $ git rebase develop</tt> You may need to resolve conflicts that occur when a file on the development trunk and one of your files have both been changed. Edit each file to resolve the differences, then commit the fixes to your development server repo and test. Each file will need to be “added” before running a “commit.”<br />
<br />
<pre>$ git add &lt;filename&gt;<br />
$ git commit </pre><br />
To push the updates to your GitHub repo, replace 100-retweet-bugfix with your branch name and run:<br />
<br />
<pre>$ git flow feature publish 100-retweet-bugfix</pre><br />
== Send Diaspora a pull request on GitHub ==<br />
<br />
Github will notify us and we’ll review your patch and either pull it in or comment on it<br />
<br />
Helpful hint: You can always edit your last commit message by using:<br />
<br />
<pre>$ git commit --amend</pre><br />
== Some gotchas ==<br />
<br />
'''''Be careful not to commit any of your configuration files, logs, or throwaway test files to your GitHub repo.''''' These files can contain information you wouldn’t want publicly viewable and they will make it impossible to merge your contributions into the main development trunk of Diaspora.<br />
<br />
Most of these special files are listed in the ''.gitignore'' file and won’t be included in any commit, but you should carefully review the files you have modified and added before staging them and committing them to your repo. The git status command will display detailed information about any new files, modifications and staged.<br />
<br />
<pre>$ git status </pre><br />
'''''One thing you may not want to do is to issue a git commit with the -a option. This automatically stages and commits every modified file that’s not expressly defined in .gitignore, including your crawler logs.'''''<br />
<br />
<pre>$ git commit -a </pre><br />
<br />
<br />
== What’s git-rebase? ==<br />
<br />
Using <tt>git-rebase</tt> helps create clean commit trees and makes keeping your code up-to-date with the current state of upstream easy. Here’s how it works.<br />
<br />
Let’s say you’re working on Issue #212 a new plugin in your own branch and you start with something like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B #develop</pre><br />
You keep coding for a few days and then pull the latest upstream stuff and you end up like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B--C--D--E--F #develop</pre><br />
So all these new things (C,D,..F) have happened since you started. Normally you would just keep going (let’s say you’re not finished with the plugin yet) and then deal with a merge later on, which becomes a commit, which get moved upstream and ends up grafted on the tree forever.<br />
<br />
A cleaner way to do this is to use rebase to essentially rewrite your commits as if you had started at point F instead of point B. So just do:<br />
<br />
<pre>git rebase develop 212-my-new-plugin</pre><br />
git will rewrite your commits like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B--C--D--E--F #develop</pre><br />
It’s as if you had just started your branch. One immediate advantage you get is that you can test your branch now to see if C, D, E, or F had any impact on your code (you don’t need to wait until you’re finished with your plugin and merge to find this out). And, since you can keep doing this over and over again as you develop your plugin, at the end your merge will just be a fast-forward (in other words no merge at all).<br />
<br />
So when you’re ready to send the new plugin upstream, you do one last rebase, test, and then merge (which is really no merge at all) and send out your pull request. Then in most cases, a reviewer has a simple fast forward on her end (or at worst a very small rebase or merge) and over time that adds up to a simpler tree.<br />
<br />
More info on the git man page here: [http://schacon.github.com/git/git-rebase.html Git rebase: man page]<br />
<br />
[[Category:Developers]]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=User:Cocoa&diff=303User:Cocoa2012-11-26T19:46:14Z<p>Cocoa: </p>
<hr />
<div>github : [https://github.com/davecocoa davecocoa]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=User:Cocoa&diff=302User:Cocoa2012-11-26T19:45:57Z<p>Cocoa: Created page with "github : [https://github.com/davecocoa]"</p>
<hr />
<div>github : [https://github.com/davecocoa]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=Federation_logger&diff=300Federation logger2012-11-26T19:13:43Z<p>Cocoa: /* Party */</p>
<hr />
<div>The Federation logger is a tool that outputs the high-level federation events (like sending a status message or photos) to be able to see, what is going on “behind the scenes”. So, if you have a test environment for Diasproa set up, you can help us test and improve federation.<br />
<br />
There is also a [screencast], if you prefer to listen instead of reading ;)<br />
<br />
== Preparation ==<br />
<br />
(All commands assume you are running them in the diaspora root directory.)<br />
<br />
To get the federation test environment set up, you have to copy the blocks containing the configuration in <tt>config/database.yml.example</tt> and <tt>config/application.yml.example</tt> to your actual config files in <tt>config/database.yml</tt> and <tt>config/application.yml</tt>. Just paste the snippets at the bottom of the corresponding file.<br />
<br />
==== config/database.yml ====<br />
<br />
<pre class="yaml">integration1:<br />
&lt;&lt;: *common<br />
database: diaspora_integration1<br />
integration2:<br />
&lt;&lt;: *common<br />
database: diaspora_integration2</pre><br />
==== config/application.yml ====<br />
<br />
<pre class="yaml">integration1:<br />
&lt;&lt;: *defaults<br />
pod_url: &quot;http://localhost:3001/&quot;<br />
serve_static_assets: true<br />
<br />
integration2:<br />
&lt;&lt;: *defaults<br />
pod_url: &quot;http://localhost:3002/&quot;<br />
serve_static_assets: true</pre><br />
Next, you have to run a rake command, that will set up the two databases and prepare the tables. (This will take a while…)<br />
<br />
<pre>$ bundle exec rake db:integration:prepare</pre><br />
When that is done, you have to delete the <tt>public/.well-known</tt> directory (if it exists), because you will be running two servers from the same code base and this directory contains cached data that would normally contain the hostname of the server which is important for server-to-server user discovery, but in this case it has to go.<br />
<br />
<pre>$ rm -rI public/.well-known</pre><br />
<br />
== Starting ==<br />
<br />
Now, we’re going to start the servers. By running the following command you should see two redis servers, two workers and two application servers spinning up for the federation test environment. (Again, this will take some time and a lot of RAM…)<br />
<br />
<pre>$ bundle exec foreman start -f FederationProcfile</pre><br />
After everything has started up, you can open two browsers (yes, either two different ones, or two windows of the same, with one in the ‘incognito’ mode. That’s because you need two different sessions…), and open them on <tt>http://localhost:3001/</tt> and <tt>http://localhost:3002/</tt> and register a new user on each of them … you will have to remember which user is on which server. When that is done, you can search the user from one server with the user on the other server and connect them by adding them to each others aspects.<br />
<br />
This alone should have already triggered our federation logger. You can check it out by looking at the logfile.<br />
<br />
<pre>$ tail -f log/federation_logger.log</pre><br />
== Party ==<br />
<br />
That’s it. You should now be able to log federation events and - if something goes wrong - provide log files from both ends for superior debugging.<br />
<br />
Althoug we’re now able to do some basic logging of events between servers, this is not by far a complete tool that does everything. You are very welcome to improve upon the setup process or the behaviour by submitting [[Pull_Request_Guidelines|pull requests]].<br />
<br />
And as always, if anything goes wrong or you need help, join us on [[How_We_Communicate#IRC|IRC]] or post on our [[How_We_Communicate#Mailing_Lists|mailing list]].<br />
<br />
[[Category:Developers]]<br />
[[Category:Federation]]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=Development_features_wishlist&diff=299Development features wishlist2012-11-26T19:08:22Z<p>Cocoa: removing a section which I completed =)</p>
<hr />
<div>__NOTOC__ <br />
<br />
Below is a curated feature wishlist of things '''the core team''' love to have some help with for the Diaspora project.<br />
<br />
'''If you choose one these features, a core team member will help you get your pull request merged'''. It is a fast track way to get involved with the Diaspora* codebase.<br />
<br />
'''Community developers are more than welcome to dive in and work on these at any time, please [https://groups.google.com/forum/?fromgroups#!forum/diaspora-dev contact the mailing list] about any of the items listed below that you’d like to help with. Also, don’t be afraid to join in and help out other developers with existing projects'''<br />
<br />
“In Development” items will be linked with a thread to Google groups, so as to encourage collaboration and avoid duplicating effort.<br />
<br />
=== 2) [https://groups.google.com/forum/?fromgroups#!topic/diaspora-dev/XcWTJn-IsUY Refactor AppConfig and EnviromentConfiguration.(In Progress)] ===<br />
<br />
AppConfig is the current class that handles loading Diaspora’s settings from application.yml. It has grown into a bit of beast, worring about bootstate, data munging, and a few related helpers. The time to clean it up is now! We should move all logic out of AppConfig, and let it just be a SettingsLogic class. Then, we should access everything via EnviromentConfiguration, delegating applicable keys and to AppConfig.<br />
<br />
=== 3) Help make things easier for other developers ===<br />
<br />
Many projects have a script which makes it trivial to get a development enviroment running. It would be awesome to have a script that bootstraped the minimum enviroment needed to run the entire test suite. That way, it would be easy for new developers to clone the repo, run the script, and run the tests, all in one swoop. As a start, which should make this process seamless for the following three enviroments(then we can work on something more general. 5) mac os x 7) ubuntu development<br /><br />
8) virtual Box Setup(we can host the final box)<br />
<br />
=== 4) Refactor Cucumber Features: ===<br />
<br />
See these(https://github.com/diaspora/diaspora/blob/master/features/post_viewer.feature)? Now see how much worse this is?( https://github.com/diaspora/diaspora/blob/master/features/edits_profile.feature). A lot of our cukes are messy, it’d be great if someone with a great sense of code clarity were to step up to the plate and refactor some of the features. If you want to go the extra mile, work with dennis and Identify tests that would be better in jasmine, or unit tests to shave some time off the suite as well.<br />
<br />
=== 5) Refactor controllers ===<br />
<br />
There are a bunch of things a seasoned Rails dev would want to do here. Utilize more rescue_froms to reduce branching, breaking really big actions into objects that are delegated to, to just improving and backfilling tests. This is not the most glamorous of things on this list, but it would be much appreciated.<br />
<br />
=== 6) Improve admin interface ===<br />
<br />
We already have rails admin running. It might still need some configuration tweaking. We could make a couple of static pages, and move some of our custom functionality to the rails_admin side of things. Other ideas are basic webfingering other pod dev tools, showing the list of connected pods, and adding links to things like resque status etc etc.<br />
<br />
=== 7) Pod Customization [https://groups.google.com/forum/?fromgroups#!topic/diaspora-dev/i4_wvLQaZJ8 (In Progress)]. ===<br />
<br />
We’re discussing how to turn some variables into strings to make pod customization easier for podmins without needing to fork from the main codebase. It’s a great starting point for figuring out how further to customize a pod.<br />
<br />
=== 8) Save image dimensions with every image file ===<br />
<br />
needs to upgrade carrier-wave, and include a hack in the carrierwave wiki.<br />
<br />
=== 8b) related, fixed delayed image processing BS. ===<br />
<br />
Ask Max for more info.<br />
<br />
=== 9) Welcome email ===<br />
<br />
After a user has signed up, email them with helpful information.<br />
<br />
=== 10) [https://groups.google.com/forum/?fromgroups#!topic/diaspora-dev/GkZTsDyTZCw Clean out Images folder (In Progress)] ===<br />
<br />
There’s a lot of unused images in there that we don’t need, so it kind of makes for a waste of space.<br />
<br />
=== 11) Carrier-Wave Improvements ===<br />
<br />
Make Carrier-Wave upload to a /tmp directory for tests, and clean up when done.<br />
<br />
=== 12) Improve Mobile Site ===<br />
<br />
Currently, our mobile site is relatively simplistic, and could use some tweaking to be made more accessible. A discussion needs to happen to figure out what new features would be desirable.<br />
<br />
=== 13) Add Tests to [https://github.com/diaspora/diaspora/tree/xray7224-adds-lang-url-param This Pull Request] ===<br />
<br />
This was contributed to us by a user. It’s a relatively simple fix, but the contributor was unable to write tests for it. Let’s help this person out and make sure that we can get it merged in!<br />
<br />
=== 14) Document the code. ===<br />
<br />
Please document the existing code and also consider documenting your code as much as you can when you send us a pull request. It helps others who fork the repository to understand and work on it.<br />
<br />
== New things to be worked on ==<br />
<br />
things needed to be fixed at hand.. started from a conversation between @raven24 and @maxwell<br />
<br />
evil query …. use the scope_operators from makrio https://github.com/makrio/makrio/blob/master/config/initializers/scope_operators.rb (btw. the amount of inline code comments is probably not TOO DAMN HIGH# enough - I think we really want to get the wisdom inside/next to the source, rdoc for (most of) the code might be helpful for new devs…) get some SQL wisdom in there (… what else did I do those two Database-courses for?)<br />
<br />
→ so, maybe a walk-through of the evil query parts might help (soon-ish)<br />
<br />
Batch stuff using find_each more http://apidock.com/rails/ActiveRecord/Batches/ClassMethods/find_each -&gt; possibly together with resque/sidekiq switch - receive loop - sending loop<br />
<br />
Federation and stuff make receive be runnable again and again encapsulate into objects and separate into layers (throw a HTTP request at the “federation layer” and out comes normalized XML/JSON - or the other way around) notifications…. de-fuckify them - don’t try to use more magic than we actually can handle. better more verbose code than a mess that causes problems - completely decouple them from federation state. move federation to json? Maybe start over? general theme of trying to think of discrete phases? - decouple database layout from the protocol messages structure object serialization. - be liberal in making multiple ruby classes - serialize to an in-memory presenter, which dumps to an ORM object - allow db state to reach across in memory objects<br />
<br />
# receive message<br />
# validate envelope, parse json, put in queue =&gt; return actual response …<br />
<br />
Background Processing resque =&gt; sidekiq advantage: Threads instead of Processes, less memory more fun potential job for junior-devs, API looks similar<br />
<br />
Rails upgrade - gems - security!<br />
<br />
[[Category: Developers]]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=Talk:Contact_model&diff=298Talk:Contact model2012-11-26T19:04:04Z<p>Cocoa: Created page with "initial version grabbed from a great answer to a question on github =) https://github.com/diaspora/diaspora/issues/3763"</p>
<hr />
<div>initial version grabbed from a great answer to a question on github =) https://github.com/diaspora/diaspora/issues/3763</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=Contact_model&diff=297Contact model2012-11-26T19:03:19Z<p>Cocoa: Created page with "This is a proxy class for describing relationships between users and can best be understood through an example. The columns are labled in a confusing manner: * A contact has..."</p>
<hr />
<div>This is a proxy class for describing relationships between users and can best be understood through an example.<br />
<br />
The columns are labled in a confusing manner:<br />
<br />
* A contact has a user, that is you and the perspective we're using from now on.<br />
* A contact has a person that is the other entity in the relationship.<br />
* A connection is thus modelled through two contacts, stored in the database that the user belongs to (can be the same one for local connections). receiving means that the person is receiving posts from the user, given the person can see them (public or matching an aspect_membership).<br />
* sharing is a pure indicator if the person is sharing with the user.<br />
<br />
Given we have userA with personA and userB with personB we can have the following situations.<br />
<br />
* No contacts at all or contacts with receiving = 0 and sharing = 0: Users do not follow or share with each other.<br />
* contactAB with receiving = 1 and sharing = 0: Then we have contactBA with receiving = 0 and sharing = 1. userA is following personB, userB is not following personA.<br />
* contactBA with receiving = 1 and sharing = 0: Then we have contactAB with receiving = 0 and sharing = 1. userB is following personA, userA is not following personB.<br />
* contactAB with receiving = 1 and sharing = 1: Then we have contactBA with receiving = 1 and sharing = 1. A fully bi-directional relationship, both users are following each other.<br />
<br />
Following and sharing are synonym terms, their perspective is just a little bit different.</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=FAQ_for_developers&diff=296FAQ for developers2012-11-26T18:57:10Z<p>Cocoa: /* I have found an issue with federation, how can I debug it? */</p>
<hr />
<div>We've started adding questions that we see a lot to this page, but it doesn't cover everything.<br />
If you have other questions, the best way to get an answer quickly is to visit us in IRC. <br />
You might think, "IRC? For real? Is this 1994 again?" <br />
<br />
Yes. I mean, '''no!''' Just think of IRC as the open-source equivalent of a Campfire that developers sit around. ''Links to IRC channels and mailing lists are at the bottom of this page.''<br />
<br />
== How do I get the latest source? ==<br />
<br />
Pull the latest from github.<br />
<br />
git pull<br />
<br />
Install any updates to gems:<br />
<br />
bundle install<br />
<br />
<br />
<br />
== How do I reset the database to a totally clean state? ==<br />
<br />
<br />
rake db:drop<br />
rake db:create<br />
rake db:schema:load<br />
<br />
<br />
== How do I get debug information? ==<br />
<br />
You can use the command <br />
<br />
tail -f log/development.log<br />
<br />
to watch the log in development mode. <br />
<br />
<br />
== I have found an issue with federation, how can I debug it? ==<br />
<br />
We actually provide a special configuration for testing server-to-server communication, which produces logs that contain only the events around federation. It involves spinning up two Diaspora* instances which you can use to recreate realistic circumstances and the logs of both sides are recorded into a single file. <br />
See [[Federation_Logger | Federation Logger]]<br />
<br />
== What if my question isn't answered here? ==<br />
<br />
<br />
'''IRC Channels'''<br />
<br />
IRC is the best way to get an answer quickly. Click the link to the join the channel in a new <br />
browser window. You can also download and use an IRC client such as <br />
[http://colloquy.info/ Colloquy] for OS X, [http://xchat.org/ XChat] for GNU/Linux or <br />
[http://www.mirc.com/ mIRC] for Windows.<br />
<br />
* [http://webchat.freenode.net/?channels=diaspora #diaspora on irc.freenode.net] - general discussion and help for folks installing Diaspora<br />
* [http://webchat.freenode.net/?channels=diaspora-dev #diaspora-dev on irc.freenode.net] - discussion of the source code and help for new developer contributors<br />
* [http://webchat.freenode.net/?channels=diaspora-de #diaspora-de on irc.freenode.net] - discussion in German.<br />
<br />
'''Mailing lists'''<br />
<br />
We have two mailing lists, both Google groups. They tend to have a slightly different audience than<br />
the IRC channels, so if you can't get your question answered in IRC, you can try here.<br />
<br />
* [http://groups.google.com/group/diaspora-discuss Discussion list] - Google group for discussion of non-technical topics<br />
* [http://groups.google.com/group/diaspora-dev Development discussion list] - Google group for discussion of installation, source code, and other technical topics<br />
<br />
[[Category:Developers]]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=FAQ_for_developers&diff=295FAQ for developers2012-11-26T18:54:47Z<p>Cocoa: /* I have found an issue with federation, how can I debug it? */</p>
<hr />
<div>We've started adding questions that we see a lot to this page, but it doesn't cover everything.<br />
If you have other questions, the best way to get an answer quickly is to visit us in IRC. <br />
You might think, "IRC? For real? Is this 1994 again?" <br />
<br />
Yes. I mean, '''no!''' Just think of IRC as the open-source equivalent of a Campfire that developers sit around. ''Links to IRC channels and mailing lists are at the bottom of this page.''<br />
<br />
== How do I get the latest source? ==<br />
<br />
Pull the latest from github.<br />
<br />
git pull<br />
<br />
Install any updates to gems:<br />
<br />
bundle install<br />
<br />
<br />
<br />
== How do I reset the database to a totally clean state? ==<br />
<br />
<br />
rake db:drop<br />
rake db:create<br />
rake db:schema:load<br />
<br />
<br />
== How do I get debug information? ==<br />
<br />
You can use the command <br />
<br />
tail -f log/development.log<br />
<br />
to watch the log in development mode. <br />
<br />
<br />
== I have found an issue with federation, how can I debug it? ==<br />
<br />
We actually provide a special configuration for testing server-to-server communication, which produces logs that contain only the events around federation. It involves spinning up two Diaspora* instances which you can use to recreate realistic circumstances and the logs of both sides are recorded into a single file. <br />
See [[/Developers/Federation_Logger | Federation Logger]]<br />
<br />
== What if my question isn't answered here? ==<br />
<br />
<br />
'''IRC Channels'''<br />
<br />
IRC is the best way to get an answer quickly. Click the link to the join the channel in a new <br />
browser window. You can also download and use an IRC client such as <br />
[http://colloquy.info/ Colloquy] for OS X, [http://xchat.org/ XChat] for GNU/Linux or <br />
[http://www.mirc.com/ mIRC] for Windows.<br />
<br />
* [http://webchat.freenode.net/?channels=diaspora #diaspora on irc.freenode.net] - general discussion and help for folks installing Diaspora<br />
* [http://webchat.freenode.net/?channels=diaspora-dev #diaspora-dev on irc.freenode.net] - discussion of the source code and help for new developer contributors<br />
* [http://webchat.freenode.net/?channels=diaspora-de #diaspora-de on irc.freenode.net] - discussion in German.<br />
<br />
'''Mailing lists'''<br />
<br />
We have two mailing lists, both Google groups. They tend to have a slightly different audience than<br />
the IRC channels, so if you can't get your question answered in IRC, you can try here.<br />
<br />
* [http://groups.google.com/group/diaspora-discuss Discussion list] - Google group for discussion of non-technical topics<br />
* [http://groups.google.com/group/diaspora-dev Development discussion list] - Google group for discussion of installation, source code, and other technical topics<br />
<br />
[[Category:Developers]]</div>Cocoahttps://wiki.diasporafoundation.org/wiki/index.php?title=Git_workflow&diff=278Git workflow2012-11-19T22:15:07Z<p>Cocoa: </p>
<hr />
<div>If you’re a developer who wants to work on the Diaspora source code and submit your changes for consideration to be merged into core Diaspora* code, here’s how. Thanks to [https://github.com/ginatrapani/ThinkUp ThinkUp] for their awesome developer guide, which inspired ours.<br />
<br />
= Branching model =<br />
<br />
Firstly the most important part, the branching model that Diaspora follows. Our branching model is based on [http://nvie.com/posts/a-successful-git-branching-model/ a post on Git branching models] by [http://nvie.com/about/ nvie].<br />
<br />
In short, the model is explained nicely in this picture: [[Image:http://nvie.com/img/2009/12/Screen-shot-2009-12-24-at-11.32.03.png|nvie git branching model]]<br />
<br />
To make following this model easier we use [https://github.com/nvie/gitflow git-flow] which contains high level extensions for this Git branching model. Please start by [https://github.com/nvie/gitflow/wiki/Installation installing the git-flow extensions] as per installation instructions on their project page. There is also [http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/ a blog post] explaining in short how git-flow basics work.<br />
<br />
Please note that the usage of git-flow extensions for Diaspora* does not stop the usage of vanilla git commands! If you are not able to use git-flow or do not feel comfortable with using it, please feel free to use normal git commands. But we do enforce the branching model so please read the branching model post carefully and follow the guidelines closely.<br />
<br />
Discussion on improving this branching model happens on [http://loom.io/discussions/628 Loom.io].<br />
<br />
= Quickfire Do’s and Don’t’s =<br />
<br />
If you’re familiar with git and GitHub, here’s the short version of what you need to know. Once you fork and clone the Diaspora code:<br />
<br />
* '''Never, ever, do anything in master branch. The branch develop is the head of development, master is for stable releases!'''<br />
* '''Don’t develop on the develop branch.''' Always create a feature branch specific to [https://github.com/diaspora/diaspora/issues the issue] you’re working on. Name it by issue # and description. For example, if you’re working on Issue #359, an aspect naming fix, your feature branch should be called 359-aspect-names. If you decide to work on another issue mid-stream, create a new branch for that issue–don’t work on both in one branch.<br />
* '''Do not merge''' the upstream develop with your feature branch; '''rebase''' your branch on top of the upstream develop.<br />
* '''A single feature branch should represent changes related to a single issue.''' If you decide to work on another issue, create another feature branch from develop.<br />
<br />
= Step-by-step (the short version) =<br />
<br />
# Fork on GitHub (click Fork button)<br />
# Clone to computer (<tt>$ git clone git@github.com:you/diaspora.git</tt>)<br />
# Don’t forget to cd into your repo: (<tt>$ cd diaspora/</tt>)<br />
# Set up remote upstream (<tt>$ git remote add upstream git://github.com/diaspora/diaspora.git</tt>)<br />
# If you use git-flow initialize it: <tt>git checkout master &amp;&amp; git flow init -d &amp;&amp; git checkout develop</tt><br />
# Start working on a new issue or feature (<tt>$ git flow feature start 100-description</tt>, naming convention is ''issuenumber-description'', if you don’t have a bug report no worries just skip the number)<br />
# Develop on feature. (<tt>$ git add . ; git commit -m 'commit message'</tt>)<br />
# Push branch to GitHub (<tt>$ git flow feature publish 100-description</tt> or simply <tt>git push -f</tt>, just to stop you losing local changes on the event of hardware failure)<br />
# Fetch upstream (<tt>$ git fetch upstream</tt>)<br />
# Update local develop (<tt>$ git checkout develop; git pull upstream develop</tt>)<br />
# Switch back to feature (<tt>$ git flow feature checkout 100-new-feature ; git rebase develop</tt>)<br />
# Repeat steps 6-9 till dev is complete<br />
# Rebase develop in to feature branch (<tt>$ git rebase develop feature/100-description</tt>)<br />
# Publish feature branch to Github (<tt>$ git flow feature publish 100-description</tt>)<br />
# Issue pull request for develop branch (Click Pull Request button)<br />
<br />
Note! Do not do <tt>git flow feature finish</tt> for your branch. Submit the whole feature branch as a pull request instead without finishing it. It will be merged to ''develop'' by a reviewer.<br />
<br />
= Step-by-step (the long version) =<br />
<br />
If you’re new to git and GitHub, here’s the longer version of these instructions.<br />
<br />
== Install git and git-flow ==<br />
<br />
# [http://git-scm.com/downloads Install Git for your platform]<br />
# [https://github.com/nvie/gitflow/wiki/Installation Install git-flow extensions] IF available for your platform<br />
# (Optional but highly recommended) [https://github.com/bobthecow/git-flow-completion Install git-flow completion] for some bash auto-complete magic<br />
<br />
== Create an account on GitHub and fork the Diaspora repository. ==<br />
<br />
# Create a free account on GitHub, and log in.<br />
# Go to [http://github.com/diaspora/diaspora the main Diaspora page on GitHub].<br />
# Click the “Fork” button near the top of the screen. This will get you your own copy that you can make changes to. [[Image:http://img.skitch.com/20101018-j5xmmrs6ccn9ku2gic12y13cf9.png]]<br />
<br />
== Establish connectivity between your GitHub account and your development machine. ==<br />
<br />
# Generate an SSH key on your development machine. Here’s a “good guide”:http://help.github.com/key-setup-redirect that gives you specific directions for whatever OS you’re accessing the page with.<br />
# Make sure you’ve got an SSH public key on your machine and recorded in your GitHub account. You can see your SSH Public Keys on the Account Overview section of your GitHub account. [[Image:http://img.skitch.com/20101018-nayqmm1ne8qdyafpjb7tib4fi4.png]]<br />
# To test the GitHub authentication run:<br />
<br />
<pre>$ ssh git@github.com</pre><br />
If all is well, you should see something like this:<br />
<br />
<pre>PTY allocation request failed on channel 0<br />
ERROR: Hi username! You've successfully authenticated, but GitHub does not provide shell access<br />
Connection to github.com closed.</pre><br />
<br />
<br />
== Clone your GitHub fork to your development machine ==<br />
<br />
Run a clone command against your GitHub fork. It will look something like this except that it will use your GitHub account name instead of “you”:<br />
<br />
<pre>$ git clone git@github.com:you/diaspora.git </pre><br />
That downloads your copy of Diaspora to a git repository on your development machine. Change directory into the new diaspora directory.<br />
<br />
Check that you have [https://github.com/nvie/gitflow git-flow] installed and run<br />
<br />
<pre>$ git checkout master<br />
$ git flow init -d <br />
$ git checkout develop</pre><br />
Now you need to install everything you need to run it - which is quite a lot of stuff. We have a guide to [http://github.com/diaspora/diaspora/wiki/Installing-and-Running-Diaspora installing and running Diaspora] which should help. Pop into #diaspora on IRC (freenode) if you have problems.<br />
<br />
You’ll know you’re done when you can run specs (in two stages - the cucumber features, which are selenium acceptance tests, and the rspec tests, which are unit tests) by doing this:<br />
<br />
<pre>$ rake spec</pre><br />
'''We try to make sure these always succeed.''' Our [http://ci.joindiaspora.com continuous integration server] will tell you if there any current failures. If you have any test failures that you don’t see on CI, come ask in the #diaspora-dev IRC channel.<br />
<br />
== Figure out what to work on ==<br />
<br />
Maybe you have a feature addition in mind, but if not, check out our [https://github.com/diaspora/diaspora/issues issue tracker], or come ask in IRC what needs doing.<br />
<br />
== Create an Issue-Specific Feature Branch ==<br />
<br />
Before you start working on a new feature or bugfix, create a new feature branch in your local repository that’s dedicated to that one change. Name it by issue number (if applicable, if there’s no issue just skip it) and description. For example, if you’re working on issue #359, a aspect naming bugfix, create a new branch called 359-aspect-names, like this:<br />
<br />
<pre>$ git flow feature start 359-aspect-names</pre><br />
== Write awesome code ==<br />
<br />
You must write unit tests for all bug fixes, no matter how small. We can help you!<br />
<br />
Edit and test the files on your development machine. When you’ve got something the way you want and established that it works, commit the changes to your branch on your development server’s git repo.<br />
<br />
<pre>$ git add &lt;filename&gt;<br />
$ git commit -m 'Issue #359: Some kind of descriptive message' </pre><br />
You’ll need to use git add for each file that you created or modified. There are ways to add multiple files, but I highly recommend a more deliberate approach unless you know what you’re doing.<br />
<br />
Then, you can push your new branch to GitHub, like this (replace 359-aspect-names with your branch name):<br />
<br />
<pre>$ git flow feature publish 359-aspect-names</pre><br />
You should be able to log into your GitHub account, switch to the branch, and see that your changes have been committed. Then click the Pull button to request that your commits get merged into the Diaspora development trunk.<br />
<br />
== Keep Your Repository Up to Date ==<br />
<br />
In order to get the latest updates from the development trunk do a one-time setup to establish the main GitHub repo as a remote by entering:<br />
<br />
<pre>$ git remote add upstream git://github.com/diaspora/diaspora.git</pre><br />
Verify you’ve now got “origin” and “upstream” remotes by entering:<br />
<br />
<pre>$ git remote</pre><br />
You’ll see upstream listed there.<br />
<br />
== Rebase Your Development Branch on the Latest Upstream ==<br />
<br />
To keep your development branch up to date, rebase your changes on top of the current state of the upstream master. Check out ''[[#gitrebase1|What’s git-rebase?]]'' below to learn more about rebasing.<br />
<br />
If you’ve set up an upstream branch as detailed above, and a development branch called 100-retweet-bugfix, you’d update upstream, update your local master, and rebase your branch from it like so:<br />
<br />
<tt>$ git fetch upstream $ git checkout develop $ git pull upstream develop $ git flow feature checkout 100-retweet-bugfix [make sure all is committed as necessary in branch] $ git rebase develop</tt> You may need to resolve conflicts that occur when a file on the development trunk and one of your files have both been changed. Edit each file to resolve the differences, then commit the fixes to your development server repo and test. Each file will need to be “added” before running a “commit.”<br />
<br />
<pre>$ git add &lt;filename&gt;<br />
$ git commit </pre><br />
To push the updates to your GitHub repo, replace 100-retweet-bugfix with your branch name and run:<br />
<br />
<pre>$ git flow feature publish 100-retweet-bugfix</pre><br />
== Send Diaspora a pull request on GitHub ==<br />
<br />
Github will notify us and we’ll review your patch and either pull it in or comment on it<br />
<br />
Helpful hint: You can always edit your last commit message by using:<br />
<br />
<pre>$ git commit --amend</pre><br />
== Some gotchas ==<br />
<br />
'''''Be careful not to commit any of your configuration files, logs, or throwaway test files to your GitHub repo.''''' These files can contain information you wouldn’t want publicly viewable and they will make it impossible to merge your contributions into the main development trunk of Diaspora.<br />
<br />
Most of these special files are listed in the ''.gitignore'' file and won’t be included in any commit, but you should carefully review the files you have modified and added before staging them and committing them to your repo. The git status command will display detailed information about any new files, modifications and staged.<br />
<br />
<pre>$ git status </pre><br />
'''''One thing you may not want to do is to issue a git commit with the -a option. This automatically stages and commits every modified file that’s not expressly defined in .gitignore, including your crawler logs.'''''<br />
<br />
<pre>$ git commit -a </pre><br />
<br />
<br />
== What’s git-rebase? ==<br />
<br />
Using <tt>git-rebase</tt> helps create clean commit trees and makes keeping your code up-to-date with the current state of upstream easy. Here’s how it works.<br />
<br />
Let’s say you’re working on Issue #212 a new plugin in your own branch and you start with something like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B #develop</pre><br />
You keep coding for a few days and then pull the latest upstream stuff and you end up like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B--C--D--E--F #develop</pre><br />
So all these new things (C,D,..F) have happened since you started. Normally you would just keep going (let’s say you’re not finished with the plugin yet) and then deal with a merge later on, which becomes a commit, which get moved upstream and ends up grafted on the tree forever.<br />
<br />
A cleaner way to do this is to use rebase to essentially rewrite your commits as if you had started at point F instead of point B. So just do:<br />
<br />
<pre>git rebase develop 212-my-new-plugin</pre><br />
git will rewrite your commits like this:<br />
<br />
<pre> 1---2---3 #212-my-new-plugin<br />
/<br />
A---B--C--D--E--F #develop</pre><br />
It’s as if you had just started your branch. One immediate advantage you get is that you can test your branch now to see if C, D, E, or F had any impact on your code (you don’t need to wait until you’re finished with your plugin and merge to find this out). And, since you can keep doing this over and over again as you develop your plugin, at the end your merge will just be a fast-forward (in other words no merge at all).<br />
<br />
So when you’re ready to send the new plugin upstream, you do one last rebase, test, and then merge (which is really no merge at all) and send out your pull request. Then in most cases, a reviewer has a simple fast forward on her end (or at worst a very small rebase or merge) and over time that adds up to a simpler tree.<br />
<br />
More info on the git man page here: [http://schacon.github.com/git/git-rebase.html Git rebase: man page]<br />
<br />
[[Category:Developers]]</div>Cocoa