Draft: Github development process

This page is a draft page to document how development with Github works.

Starting a new branch

Before starting a new branch, wrap up any changes you are making by either stashing them or committing them to the current branch you are on.

Expand: Need to explain stashing/committing still.

To start a new branch, use the branch command. You will want a descriptive name you can keep track of--for instance, the bug number you are working on. Examples:

mw@memewidth:~/dw$ git branch Bug4335/admintt

Then, to switch to this branch, use the checkout command:

mw@memewidth:~/dw$ git checkout Bug4335/admintt
Switched to branch 'Bug4335/admintt'

Managing changes

Before doing any changes to a branch, make sure you have that branch checked out. You can check this with:

git branch

It will list the branches and put an asterisk next to the one you currently have checked out. If it's not, run:

git checkout BRANCHNAME

Viewing changes

Overview:

git status

Detail:

git diff

Stashing and unstashing

Save a bunch of changes:

git stash

Put the changes back:

git stash pop

Undoing changes

Undo changes to one file:

git reset ????FILLIN????

The nuclear option:

git reset --hard

Committing changes

When committing, it's a good idea to make sure your develop branch is up to date with the Dreamwidth's version, and that your current branch is merged with those changes. See [Dev Maintenance] for instructions on that. Once you are satisfied

git commit ?????

Expand: Writing commit messages: best practices.

Pushing your changes to your repository on Github

git push origin BRANCHNAME

Making a pull request

Before making a pull request, make sure that the develop branch is up to date and you have merged the branch you are developing with it. (See Dev Maintenance for help with this.)

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:

https://github.com/USERNAME/dw-free https://github.com/USERNAME/dw-nonfree

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.

Expand: What do we want people to include in the pull request description? Bugzilla URL?

When this is done, press the "Send pull request" button.

Expand: Describe making a pull request to another repository other than the DW one!

Deleting branches

Warning: This command WILL destroy data, be careful when using it. Only delete things you are sure you want deleted.

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 the branch is also on your Github, you can delete it like this:

git push origin --delete <branchName>