Rough outline of workflow -- aka let's talk

[fu]

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

1. Create a Github account

2. Set up Git on your computer

   github:help -> "Set up Git" (provides instructions specific to each operating system)

3. Fork our code

4. 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!

5. 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
   

6. Edit your code

   This will work the same as before.

7. 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

8. 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!

9. 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
   

10. 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.

11. 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

1. 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?

2. Start from step 4 above

Making additional tweaks after a review

1. Switch back to the relevant branch

   Git flow:

   git flow feature checkout descriptive-name-bug1234
   

   Vanilla Git:

   git checkout feature/descriptive-name-bug1234
   

2. 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.

Comments

[denise]

Thank you so much for all the work you've done in putting this together so far! (Also, lol teleporter.)

I will reiterate two quick things for everybody watching: one, the process really is super fuzzy in a few places (I haven't even tried doing any of this myself because I'm the type to get really annoyed by super fuzzy process, so if you're like me, definitely just hang tight) and two, there really are a lot of subtle details that we can discuss -- fu mentioned a bunch of them at the end of her post but I'm sure everybody can think of specific scenarios that they want answers about. Right now, we really are looking for discussion on the basic workflow steps for a single bug that's being done all at once (like the ones provided here), not the more advanced stuff like collaboration or a major bug being worked on over extended time. That's all important stuff to talk about too, but we want to get the basic workflow down first.

[cesy]

git branch feature/descriptive-text-bug1234
git checkout feature/descriptive-text-1245

You can do these both at once: git checkout -b feature/descriptive-text-bug1234

Is it worth clarifying the difference between origin (your fork) and upstream (Dreamwidth main repo)? My usual process after finishing a bug and pushing it is to switch back to the master branch, pull from upstream, push to origin, then checkout a new branch for the next bug. That means the Github GUI is up-to-date and easy to use for all their visual comparison stuff.

Also, before pushing to Github / publishing and pull requesting, I usually rebase to catch any changes made while I was working, to make it easier for whoever reviews and merges the pull request.

Edit: Also, given all of this, I am contemplating getting back into DW development. Can you link me to instructions for installing DW locally, or is there any chance we could install Dropbox or another syncing option on the Dreamhacks? AO3 has had a lot of success with Dropbox on their Dreamhack equivalent.

[pauamma]

OK, I'm not interested in having my github account sitting between the git repo on my dreamhack and the main Dreamwidth github repo, so my ideal workflow would include submitting a pull request from the command line on my dreamhack. Can I do that? Pointers to TFM gratefully accepted if it explains how.

ETA: looks like https://github.com/defunkt/hub may be what I'm looking for. More later.

[baggyeyes]

I'm still scratching at learning Git myself...but I thought this reference might come in handy here too:

git - the simple guide