GitHub Usage

2019 status: Current

Are you ready to contribute to Project Buendia? That's great! Here are the guidelines we'd like you to follow so that your help will be much more efficient:

1. Create a GitHub account if you don't have one already.

   • Set it up at https://github.com

2. Fork the Project Buendia repositories into your account

   • For the server repository, fork https://github.com/projectbuendia/buendia
   • For the client repository, fork https://github.com/projectbuendia/client

3. Clone your newly forked copy into a workspace on your local machine.

   • For the server repository:

     git clone https://github.com/<username>/buendia
     cd buendia
     

   • For the client repository

     git clone --recursive https://github.com/<username>/client
     cd client
     

4. Add a remote reference to upstream, for pulling future updates.

   • For the server repository

     git remote add upstream git://github.com/projectbuendia/buendia.git
     

   • For the client repository

     git remote add upstream git://github.com/projectbuendia/client.git
     

5. As a precaution, disable merge commits to the master branch.

   git config branch.master.mergeoptions --ff-only
   

6. On GitHub, assign yourself the issue you are working on, or create an issue to describe what you are fixing and assign it to yourself.

7. Create a branch for your work. The branch name should consist of your username, a slash, and a short description (1 to 4 words) of what you're trying to fix or accomplish. Use hyphens to join the words in your description. For example, if your username is alice and you are renaming something called "FooFactory" to "BarFactory", it would be reasonable to name your branch like this:

   git checkout -b alice/rename-foo-factory
   

8. Work on the code locally.

9. As you're working, you might sometimes want to pull in new changes from the main Buendia repository and update your fork with them.

   git pull --rebase upstream dev
   git push
   

   Here, the --rebase option will automatically move your local commits, if you have any, on top of the latest branch you pull from; you can leave it off if you don't want them rebased.

10. Commit your work and push it to your forked repository.

    git commit -m 'Rename FooFactory to BarFactory.'
    git push -u origin alice/rename-foo-factory
    

11. Before you submit your work as a pull request, rebase your branch against the dev branch. This moves your changes over so that they are applied to the latest commit on dev. After rebasing, you will need to use git -f to push your new branch to your own repository.

    git fetch upstream
    git rebase -i upstream/dev
    git push -f origin alice/rename-foo-factory
    

12. Verify that your code works, and ensure that your code conforms to the project's Java Style.

13. Create a pull request with your changes. Fill in the sections in the pull request template according to the instructions there.

14. A maintainer will review your pull request and possibly ask you to make changes or address issues in it. When it's complete, the maintainer will merge your pull request into dev.

15. Pull the newly updated dev branch (which now includes your change) into your local repository.

    git checkout dev
    git pull --ff-only upstream dev