WC_Dev Guidelines

Developer Guidelines

This document contains some general guidelines for working with the WorldWide Telescope Web Client project.

Git Guidelines

This section contains some tips for working more efficiently in Git.

Create a "blessed" Remote

Follow these steps to create a "blessed" remote referencing the master branch of the main repository. You can use this remote to synchronize your repository with the newest version of the code from the main repository. This procedure is optional but recommended.

1. Open a command prompt and navigate to the openwwt-web-client folder.
2. Add a remote called "blessed". This will point to the main repo.

   git remote add blessed https://github.com/OpenWWT/openwwt-web-client.git
   

Once you have done this you should have two remotes: blessed and origin. To view the remotes for the current repo, use git remote -v.

For more information, see Working with Remotes.

Git Workflow Summary

These steps summarize a typical workflow using the blessed remote to get the latest code, and creating a topic branch to work in.

1. Navigate to the master branch of your OpenWWT-Web repo.

   git checkout master
   

2. Pull the latest from the blessed remote.

   git pull blessed master
   

3. Create a topic branch.

   git checkout -b my-new-branch
   

4. Make your changes in the new branch.

5. When you are ready, commit your changes:

   git commit -a -m "A meaningful description of my commit."
   

6. Push your local changes to your fork:

   git push origin <branch_name>
   

Now you're ready to make a pull request.

Pull Requests

When the code in your GitHub fork is ready to make its way into the master branch of the OpenWWT-Web GitHub repo, you should submit a pull request. Be detailed in your description of the changes.

When you submit a pull request, GitHub will let you know if the request cannot be merged automatically. This GitHub page explains how to merge a pull request.

Rebasing

Rebasing is another handy thing you can do to keep things tidy. As you work, you may find that you have piled up multiple commits. This can make it more difficult to integrate your work once you submit a pull request. Rebasing has the effect of collapsing all of your changes into a single commit, making it much easier for others to review and integrate your changes.

1. Open the branch you want to rebase and use this command:

   git rebase -i master
   

2. Modify the resulting text file to indicate how the rebase should be applied. Instructions are in the text file.

3. Push the commit back upstream:

   git push origin yourbranchname --force