![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
![[site community profile]](https://www.dreamwidth.org/img/comm_staff.png){kind=small}
Rough outline of workflow -- aka let's talk
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)
-
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-bug1234To 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 commitThen 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-bug1234To 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 developIf 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-bug1234Vanilla 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.
no subject
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 --
no subject
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.
no subject
Dropbox as a solution for syncing local to Dreamhack is *brilliant*. It vastly simplifies the most fiddly bits I've been worried about. I must talk to our server admin to see what she can do.
We have Dreamwidth Scratch Installation at the moment, but hold on actually -- right now everything is as it used to be when you last tried out DW Dev. We don't have the code changes in place to support this workflow -- yet!
no subject
I am excited; I think you might know -- have you ever have to worry about rebase when it comes to longer-running branches? Or hmm actually the one that worries me is rebasing when two of you are working on the same branch; has that come up as an issue that you've had to solve? (Merging instead in those specific cases?)
no subject
I'm not sure if I've explained that very well - let me know if it doesn't make sense. Basically person A starts off from master, codes part 1 of the new feature, pushes. B pulls that branch, codes part 2. Meanwhile, A codes part 3 and the master moves ahead with other development. B finishes part 2, A publishes part 3 (without rebasing, ignoring master at this stage, since A knows B is working off zir code). B rebases off A, then pull requests to A's fork. A merges B's code, and now has a branch that contains 1, 2 and 3 all neatly. A can then rebase to master and force publishes, breaking history. B restarts the next bit of development off the back of A's neatly rewritten history, and the cycle starts again. Repeat as necessary until the feature is done, then A can pull req to the main repo, with B's commits all being appropriately credited and showing as merges into A's branch, and A's branch merged into master all at once.
no subject
Though we didn't think of B branching off A -- I think that makes a huge difference in terms of making it easy to merge back in.
Thank you!
no subject
Fu pointed me here. :) I'm curious how the AO3 manages to have Dropbox work on a single server for everybody - after all, there's no proof from Dropbox's point of view that it's not just one user using multiple accounts to get around the limit on free Dropbox accounts. So I'm curious about they've solved that, and also how you work with running multiple daemons.
no subject
When a user first sets up their hack, they start dropboxd and get the prompt to link their computer to an account. They create a brand new Dropbox account, make an "OTW-Projects" folder in it, then share that folder with their personal Dropbox account on their home computer. That lets each user edit their code on their own computer, it syncs with the 'hack, but without sharing their personal files with the rest of the 'hack users.
Each user has to start and stop their own dropbox daemon - I'm not sure how that's set up from a sysadmin point of view to stop them interfering with each other.
no subject
$HOME, so multiple instances should be fine so long as they're run by separate users :-)no subject
ETA: looks like https://github.com/defunkt/hub may be what I'm looking for. More later.
no subject
mkdir dw-free-git
git clone https://github.com/pauamma/dw-free dw-free-git
cd dw-free-git
git remote add upstream git://github.com/dreamwidth/dw-free.git
git fetch upstream
git branch feature/obsolete-email-bug4448
git checkout feature/obsolete-email-bug4448
vi `git grep -l fduuvrzv`
vi `git grep -l afunamatata.dw`
git commit -a
git remote set-url origin https://pauamma@github.com/pauamma/dw-free
git push --all
hub pull-request -b dreamwidth/dw-free:develop
no subject
git checkout develop
git branch andnowforsomethingcompletelydifferent
git checkout andnowforsomethingcompletelydifferent
vi README
git commit -a
git push --all
git branch feature/obsolete-email-bug4448
git checkout feature/obsolete-email-bug4448
vi cgi-bin/LJ/Console/Command/MakeInvites.pm
git push --all
hub pull-request -b dreamwidth/dw-free:develop
At this point, there are, as far as I'm concerned, 2 showstoppers with the suggested github workflow:
1- Submitting a pull request (the equivalent of uploading a patch to Bugzilla) doesn't update the bug status.
2- Merging a pull request (or whatever you call the equivalent of comitting a patch to the main hg repo) doesn't post to changelog.
I think I heard someone mention there might be a way to automate #2 (although it's not implemented yet, unless I missed something). However, I can't think of a way to get #1 without considerable manual effort. (Tracking the branch associated with the bug on the developer's own github repo, if that would notify of pull requests, would require knowing when that branch is created and what it's called, neither of which can be automated as far as I can tell.)
Anyone has an idea?
no subject
Both are solvable with this.
no subject
(I know, I know, attachment and db size, but it's a funny thought!)
no subject
no subject
no subject
no subject
http://developer.github.com/ contains info for Github. Zilla, umm http://www.bugzilla.org/docs/tip/en/html/api/ maybe? That's a few versions ahead of us, but there may be info there saying when a particular item was added.
no subject
no subject
no subject
git - the simple guide