Version Control
The Dreamwidth code uses a Git repository and is publicly available on Github.
You can orient yourself with the basics via Git Getting Started. Instructions for specific actions are below:
Contents
Starting a new branch
First, if you're currently in the midst of making changes to another branch, wrap up your changes either by stashing them or committing them. (See later sections for details.)
New branches should be started from an up-to-date copy of develop. To bring your copy of develop up to date, first use checkout to switch to the develop branch:
git checkout develop
Then bring your develop branch up to date by pulling in changes from dreamwidth's copy of develop on github:
git fetch dreamwidth git pull --ff-only dreamwidth
To create a new branch and switch your working copy over to it immediately, use git checkout -b branchname; eg
git checkout -b bug4335-admin-tt
Choose a descriptive branch name you can keep track of--in this example, it's the bug number being worked on, plus a couple of keywords so you're not relying solely on memorising bug numbers!
Managing changes
Before making changes to a branch, make sure you have that branch checked out. You can check which branch you're currently working on with:
git branch
It will list the branches and put an asterisk next to the one you currently have checked out, eg:
bug4650-update-bootstrap.pl
bug4772-stats-old-urls
bug4772-stats-old-urls-dw-style
bug5003-remove-hg-links
* develop
master
If the current branch isn't the one you want to work on, change to the right branch with the command:
git checkout BRANCHNAME
Viewing changes
To get an overview of which files have changed, which files are included in your next commit, and what new files exist, use:
git status
To get a line by line description of all of the changes, use:
git diff
When you want the changes you've made to a file you have to be included in your next commit, use git add:
git add FILE
If you make more changes to that file, you will have to add it again to have the new changes included.
Stashing and unstashing
Sometimes you may have changes you are not ready to commit yet, but need to stow away while doing tasks like merging. git stash can be useful for this.
To save a bunch of changes:
git stash
To put the changes back:
git stash pop
Undoing changes
If you have a file with changes and want to revert it to what's currently committed to the branch of the repository you are on, use:
git checkout -- FILENAME
If you accidentally added a file to the staging area you are going to be committing, you can unadd it using:
git reset HEAD FILENAME
If you want to reset ALL files to what's currently committed to the branch of the repository you are on and discard all changes (DO NOT USE IF YOU WANT TO SAVE ANYTHING), use:
git reset --hard
Committing changes
Use git add to add the changes you want to commit. Before committing, you may want to briefly review your changes with git status and git diff.
Once you are satisfied that these changes are the ones you want to make, give the command:
git commit
This will open up the command line editor specified in your config. (You can change this with instructions in Git settings.) Write up a good description of the changes included in this commit.
Git commit messages have a format that's rather peculiar to Git:
First line is a v.short summary: 50 chars or less After a blank line, give a long-form description of the changes. You can write a few sentences, several paragraphs, or an essay complete with theorems, premises, and supporting references -- whatever is needed to clearly document the change.
The first line is used as a summary by tools like git log --oneline; if it is too long, the output of these tools will display oddly.
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
If you are making a commit that only needs a short explanation, you can use the -m option:
git commit -m "(Bug 3492) This describes the change that I just made."
Pushing your changes to your repository on Github
After committing your changes, you need to push them to your repository on Github. You can do this with:
git push origin BRANCHNAME
Making a pull request
Bring your branch up to date with develop
Before making a pull request, it's good etiquette to bring your branch up to date with any changes that have happened in develop since you initially forked your branch. Once you've made the last of your commits, double-check that you're in the branch you want to submit:
git branch
Then fetch changes from Dreamwidth's develop branch and bring your branch up to date with them:
git fetch dreamwidth git pull --rebase --ff-only dreamwidth develop
pull --rebase incorporates any new changes from develop into your branch, and it also reorganizes your changes so that changes in your branch appear to start from current develop, instead of where develop was when you initially started your branch. (Neat!) This can make it much easier to merge your branch into Dreamwidth's main develop branch.
Submit!
Then, once everything is all up to date, go to your version of the repository (dw-free or dw-nonfree) that you want to send upstream. By default they should be at:
These repositories are separate, so if you have made changes to both of them, you will have to submit pull requests for both of them.
Find the "Pull Request" button (by "Unwatch") under the top toolbar. Click it and you will be brought to the pull request page.
Ideally, the initial page should say something like "Oops! dreamwidth:develop is already up-to-date with USERNAME:develop Try a different branch?" That's good--that means that your develop branch is up to date with Dreamwidth's!
Find the "head branch" drop down and select the branch you want to submit a pull request for (e.g. "bug4335-admin-tt" as per the example given in #Starting a new branch).
When this is done, press the "Send pull request" button.
Finally (and optionally!), go back to the Bugzilla page for your bug, and leave a comment linking to the pull request you've just submitted.
Deleting branches
You might create a branch by mistake, or have your changes pulled into the main develop branch on Dreamwidth. To delete the branch locally, use the command:
git branch -d BRANCHNAME
If it's a branch that hasn't been merged yet, the above command will give you an error. If you are SURE you still want to delete that branch, use:
git branch -D BRANCHNAME
If the branch is also on your Github, you can delete it like this:
git push origin --delete <branchName>
