Skip to content

Contributing

Jump to bottom
Daniel Aquino edited this page Feb 28, 2014 · 22 revisions

Information on contributing to Forsaken.

Note this page was shamelessly based off of https://github.com/joyent/node/wiki/Contributing :]

Getting your code into Forsaken

The only "official" Forsaken repository is https://github.com/ForsakenX/forsaken.

Some participation guidelines

  • Discuss large changes with others before coding (You should know how to find us by now - Chat).
  • The current coding style is a bit murky after years of passing around various developers (we will be formatting it using a tool soon) but the general idea is to try and be consistent.
  • Same goes for compiler warnings, we are working on cleaning it up since we moved from msvc to gcc but please don't introduce new ones...
  • Obviously test your code and don't try to introduce bugs..
  • Please use Safe Code while developing to help reduce crash worthy bugs and other common pitfalls (see the Compiling section).
  • Please enable .git/hooks/pre-commit as it help detect white space errors.
  • This is great read in general: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project
  • Please split up commits into single logical changes (and don't mix up white space changes with a commit): http://git-scm.com/book/en/Git-Tools-Rewriting-History#Splitting-a-Commit

Versioning

Forsaken follows a simple versioning scheme: major.network.commit:

  • Anything that will break network compatibility will require a network version bump and we generally try to avoid that as much as possible.
  • Same goes for any major change that would basically make the game not function the same for all players and/or cause us to bump the version.
  • We will make separate branches for that so we don't drive players crazy with version nightmares...

Commits

This is standard git practices here:

  • the first line should be maximum 50 characters
  • the second line should be blank
  • in fact always use an extra blank line between paragraphs
  • any additional lines should not exceed 80 characters.
  • should have the author field properly filled out with your full name and email address.
  • good idea to use imperative present tense in these messages. Instead of "I added tests for" or "Adding tests for," use "Add tests for." (http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project)

On top of that we'd like to follow a very common style:

rendering: always clear back buffer

We need to clear the back buffer to fix the rendering artifacts that
were showing up in the tunnel level.

Fixes forsakenx/forsaken#4510.

This demonstrates three key things:

  • First line is prepended with area of functionality and followed by a short and descriptive message.
  • Followed by descriptive text explaining what caused the bug.
  • Ended by referencing the bug in question.

Pull Requests

The simplest way to contribute is by using GitHub's pull request system. This guide will walk you through from creating a fork to having your first pull request accepted.

https://help.github.com/articles/using-pull-requests https://github.com/blog/712-pull-requests-2-0

First steps

Go to the repository page and hit that big Fork button in the top right. This will create your very own personal copy of the repository to which you can commit.

You can now easily clone this repo now as you normally would.

git remote -v add origin git@github.com:[your-user-name]/forsaken.git

If you already have a clone of the official repository we can change it up quickly:

git remote rename origin upstream
git remote -v add origin git@github.com:[your-user-name]/forsaken.git

To receive the latest changes we need to let the repository know where the upstream repository lives. Pull requests that don't stay up-to-date don't get pulled.

git remote -v add upstream https://github.com/joyent/node.git
git fetch upstream

Now you're setup and anxious to start hacking away with some awesome ideas. STOP. If you want a snowball's chance in hell of having your changes pulled, they need to be self contained. To do this, start by creating and checking out a new branch from master:

git checkout master
git checkout -b my_awesome_idea -t master

Now you can begin to make changes and commit them to your hearts content.

Your first commit

Quick note on committing and commit messages. First, make sure each commit contains only the relevant code changes for that commit. Don't change a single important line, then pollute it with random syntax and white space changes. If you find yourself in that circumstance read up on git interactive staging.

Now that you have staged an appropriate number of changes for a single commit, don't screw it up by using a useless commit message. Such as: 'fixed a small bug'. To prevent yourself from creating these useless commit messages, get in the habit of not using the -m parameter with git commit.

See the Commit section earlier for properly formatting your message.

GitHub automatically links to bugs in commit messages in the form of <usr>/<repo>#<issue> or GH-<issue>. Use it, please.

Use rebase and other git tools to clean up commit messages, reorder them, split, merge, etc.. http://git-scm.com/book/en/Git-Tools-Rewriting-History#Splitting-a-Commit

When updating a pull request that you've already sent in it will require you to force push since the changes have already been pushed to github.

# the + sign is for "clobber". This is better than --force
# because it will only clobber this one single thing.
# see `git help push` for more info.
git push origin +my_awesome_branch

# to clobber *everything* you can do this, but USE WITH CAUTION!
git push origin --all --force

Staying up-to-date

In the time you create a change, submit the pull request and have it accepted there will most likely be other changes that have been pushed. So now it's time to pull those changes.

If your master branch is tracking upstream then we can easily do the following:

git checkout master
git pull --rebase upstream master

And now to combine the latest from master to my_awesome_idea. How do we keep our changes up on the current upstream branch? If you're thinking merge you're mistaken. Merging your changes will make all kinds of ugly in the pull request, and nobody wants ugly. (Typically, if you do this, a committer will ask you to "rebase onto the current master". Here's how to do that.)

Instead of merge, we'll be using rebase. This will rewind your commits then reapply them to the latest. Do that with the following:

git checkout master
git pull --rebase upstream master
git checkout my_awesome_branch
git rebase master

It's possible there will be conflicts with your changes. You can either fix the conflicts then git rebase --continue or just git rebase --abort to cancel the rebase. Afterwards force push your changes with the same git push origin +my_awesome_idea. Now when you check your pull request again all you'll see are the update SHA's of each commit. And GitHub has a very nice code commenting feature where any previous comments will only be rendered outdated if the section of code was changed by the rebase.

Submission and review

Now you're ready to submit! It's actually kind of anticlimactic. Go to your repo page and click the Pull Request button in the top right. Now STOP. Have you? Yes. Ok, now look at this page. Look at it again. It's very important to understand what's on this page.

On the top left you'll see base repo and base branch. This defines where you want the pull request to go. The base repo should automatically select the upstream or cloned repository. If you've branched from master (which is all we've discussed) then make sure base branch is also set to master.

On the top right you'll see head repo and head branch. Your fork should automatically be selected in head repo. Now the really important field. Make sure head branch is the branch you've put all your blood sweet and tears into. If your pull request is only a single commit then the text fields should fill with the commit message. In any case make sure you fully explain why your pull request is so important. Now, you can hit Send pull request. There, submitted. Feel better now? Me too.

Everybody is interested in getting the best result possible, so you should be ready to respond to questions or concerns about your pull request. Don't take offense to what other developers say. Especially the core development team. If they bring something up it's for a good reason. Listen, learn and try to understand why their suggestion works. In the case you disagree with them, provide empirical reasons why (e.g. benchmarks, test cases, etc.).

From your pull request users can either leave general comments or code review comments. Code reviews will be set as outdated when the specific line of code reviewed are changed as you update the pull request branch. Use these comments to improve your pull request. Make changes, rebase your commit(s), continue to take feedback. Be prepared to consistently revisit and revise your work. Don't be surprised if it takes longer to manage the pull request than it did to make the code change.

For a more extreme example of a pull request see joyent/node#4348. Isaacs worked on this pull request for months, continued to rebase the commits against master and finally put it up for code review. This was a truly amazing amount of work that once was ready, seamlessly merged.

On a final note: Don't get discouraged. The core team has been working on Forsaken for the last 5 years and are active players, hence it can take a while to get use to the workflow and how the team operates and why things are done the way they are. Jump on IRC. Chances are someone is there ready to help.

Welcome to the community, and thanks for helping!

Clone this wiki locally