dw_dev | Rough outline of workflow -- aka let's talk (Reply)

I've been reading up on Git, trying to figure out how to document a process that works for everyone, and it just isn't working. All I know is how I want to do things, and I can only guess what would work best for everyone. So instead of my sitting here writing down guidelines, which might get set in stone even if they don't really work for you, let's actually talk about it, and then document the hell out of what we decide on.

Big bold critical disclaimer: If you are uncomfortable with really vague instructions and a process that might break at any point, just hang back and wait! This is the "We need people to try doing this so we know where the major stress points are" step.

Other disclaimer: We'll document what seems a reasonable way to do things to make it easier for anyone coming in, but that doesn't mean you need to stick to the script strictly. You can manage your code on your end however you'd like -- so long as you send that pull request!

Useful links:

github:help -- check out the beginner and intermediate sections, as well as further git resources. I don't think we'll need anything from the other sections, until we run into specific issues.
Git flow -- abstraction on top of Git to make the most common workflow more convenient

Here's what we need to figure out:

Starting from scratch

Create a Github account
Set up Git on your computer

github:help -> "Set up Git" (provides instructions specific to each operating system)
Fork our code
Pick a bug

We'd still be doing this from Bugzilla, as issues support on Git is very rudimentary, and we use Bugzilla for more things than just code bugs, so we don't want to split them. I believe that this is workable, though!
Start working on the bug

What I'd like to do is encourage each bug to occur on its own branch.

A branch is a separate line of development, one that lets you isolate your current set of changes from changes other people make. But if we do this, we'll need to explain the concept of branching, in a way that makes it seem intuitive, somehow! (Does anyone have any good suggestions of how to best explain it?)

For those playing along,

To make a branch using git-flow:
```
git flow feature start descriptive-text-bug1234
```
To make a branch using vanilla git:
```
git branch feature/descriptive-text-bug1234
git checkout feature/descriptive-text-1245
```
Edit your code

This will work the same as before.
Test your changes

Make sure your code is live on your own server (a Dreamhack will work here -- we're still talking about the best way to integrate the Dreamhack machine in the process, but at the very least we'll make sure it's very clear how to send your changes to your Dreamhack). Restart the server if necessary. Test that your changes have had the desired effect, and have not broken anything otherwise
Commit your changes

Committing means saving your current set of changes along with a description of what these changes are. "Commit early, commit often" is a good mantra. Commit at each good stopping point, or whenever you have a coherent set of changes.

To those familiar with Mercurial, let's talk about the staging area in Git. The staging area means that instead of commiting all your changes, you'll need to tell git which of the files you've changed which you want to commit this time.

It may help a bit to see this in GUI form: it's like you were presented with a list of filenames with checkboxes, and you need to check each one to include it with the current commit. The thing that trips up most people coming into Git is that when we start the commit process, nothing is checked on this list, so you have to have a separate step first of adding all the files.

This is roughly equivalent to:

Vanilla git command:
```
git add cgi-bin/DW/Teleporter.pm t/teleport.t
git commit
```
Then fill in with a commit message, example:

(Bug 1234) Make sure we always foo the bar

One complication: if you're working locally on your computer (say you want to use a GUI text editor), and have your Dreamhack as your web server -- that is, they're not both on the same computer -- it might make sense to commit first, and then push your changes to your Dreamhack for testing (command will be similar to that in step 9 below, but instead of having Github as a destination, your Dreamhack will be the destination)

The alternative so far has been to use FTP to copy over each file that you've changed -- making sure you navigate to the right directory on the Dreamhack side each time. The first option is harder to explain, the second option is way more work and runs the risk of missing something, so the question of how to handle this has been the major roadblock in this whole conversion process -- this step is the fuzziest, right now, like I said in step 7. We may ask people to try it both ways and see which one is clearer. Or if anybody has any better solutions, please please please suggest them!
Now publish your changes to Github, so other people can look at it

To do this using git-flow:
```
git flow feature publish descriptive-text-bug1234
```
To do this using vanilla git:
```
git checkout develop
git push origin descriptive-text-bug1234
```
Then ask us to take a look

Send us a pull request -- which basically means you're asking us to suck your changes into the main Dreamwidth code repository.
Wait. Respond to any questions brought up in review, or if you'd like, pick up a new bug (start from #4)

What comes after the first patch has tripped up a lot of people. The old way of doing things, and what we're discussing now are roughly similar when you're starting from scratch. It's here, after the first patch, that the difference is immediately clear.

Picking up more bugs

Update your repository from the latest code

Vanilla git:
```
# switch back to the develop branch
git checkout develop

# pull in changes
git pull upstream develop
```
If you'd had changes that aren't on their own branch, you'd have to deal with merging or rebasing here. Luckily, all your changes are set aside in another branch, yeah?
Start from step 4 above

Making additional tweaks after a review

Switch back to the relevant branch

Git flow:

git flow feature checkout descriptive-name-bug1234

Vanilla Git:

git checkout feature/descriptive-name-bug1234

Start from step 6 above

There are other things we should discuss, like how to make sure your changes are against the latest version of the repository when you submit them, how to have multiple people work collaboratively on the same bug (which is where Github really shines!), how to best adapt to a branch-y workflow as opposed to a Mercurial queue-based workflow, and the subtle details of command-line client vs GUI client. I don't want to distract from the overall goal here of trying out the basic workflow, but I'll post more about those more advanced things in a few days and we can talk them over once everybody who's interested has a chance to play around a bit.

Rough outline of workflow -- aka let's talk

Starting from scratch

Picking up more bugs

Making additional tweaks after a review

Post a comment in response: