This is a quick guide for starters and is not meant to be complete. Searching on the internet is encouraged and advised. The process of submitting a patch is done in two places: First, at your terminal. Second, at Review Board

At your console

These instructions are based for Linux. If you're using a visual git program, or windows, instructions may be different.

Getting a clone from the FreedroidRPG repository

You should have the latest development version from FreedroidRPG. You can find it on git. If you do not have a clone from it yet, you should get one now. Remember to git pull before changing anything!

Creating your own branch

By default, you are at branch "master". To make sure your changes doesn't become a huge mess, it's advised to create your own branch. This can be done by

git checkout -B my_new_branch

This way, using the "git checkout" command, without the -B flag, you can move to and fro a version from the game with your changes and a version without them.

IMPORTANT: Do NOT modify branch master! It will make your life harder!!

Committing your changes

Save your changes on git. Run the following command to have an idea of what is going on:

git status

after making sure you're not on the master branch, for every file in red (not staged, or untracked) run the following command:

git add FILE

Where FILE is the name (with extension) of the file you've modified or created. After this, simply run:

git commit

After checking that everything is fine, write a short description of your changes, and save. Your changes were saved to git.

Generating a diff

Simply run:

git diff --full-index master YOUR_BRANCH > FILENAME.patch

Where YOUR_BRANCH is the name of your branch, and FILENAME is the name you want to give to your diff. It's done for the terminal. Now to send this patch for us.

At Review Board

access the Review Board

Creating an account

Welcome to ReviewBoard! At the screen top, right corner, you should find a button for register and one for login. It is very intuitive so we won't be adding needless details. Create an account, and do not forget to fill the captcha - after all, who would like if bots from MegaSys came here and did a patch to increase their population and energy level in 9001%, right?

At the top of screen, there is the review board logo and version. This is based on version 2.5.7, instructions may differ depending on the version number.

Below the version number is a series of buttons:

  • My Dashboard
    • overview of your submissions and things of your interest
  • New Review Request
    • creates a request. We will explain in detail at next section.
  • All Review Requests
    • all requests by everyone
  • Users
    • list of users from RB
  • Groups
    • helps to filter Requests by the reviewer groups.

Creating a new request

After pressing "New Review Request", RB will inquire you about the repository. Select "1- freedroid-git" at the left bar. Drag the .patch file created earlier or select it using the button. Confirm if necessary.

Write a short description for your patch in the summary field. Fill the Description field and, if you tested it, explain how you tested and what were your results at Testing Done.

Information section have some more fields to fill. You can leave the Branch field empty. If your patch is solving one or more bugs, write their numbers, separated by commas ( , ) at Bugs field.

If it is required to apply another patch from RB - like a follow-up - fill the review request number at "depends on", but this probably is not the case.

At Reviewers, if you need someone specific to review your patch, write their username at People. Otherwise, you need to set one or more reviewer groups, depending on your patch:

  • core_reviewers
    • If your patch touches major code, C engine, etc.
  • dialog_reviewers
    • Game content, like maps, dialogs, quests and such.
  • contributors
    • This is a special group. Do not use it unless requested.

Once all required fields are filled, on the green banner entitled "This review request is a draft." press the "Publish Changes" button. Your review request is done, now you just need to wait until a developer review it. Depending on the time of the year it may happen fast, slow, or simply don't happen, on such case you must go to IRC and get some developer there to review for you. Everyone has a busy life, after all.

Updating your request

After getting a review, devs and other contributors or RB users might request changes. Usually it's not imperative, but as it is usually a good idea to follow their advice, do the changes they've asked for, and on the yellow bar click on "Update > Update Diff". Select a new diff, describe your changes on the green banner which just appeared, click on "Publish Changes" button and vĂ³ila! Your request was updated and is closer to getting ingame.

Reviewing other requests

Select an interesting title on All Review Requests section. Make sure it wasn't submitted yet.

At the request top bar you'll find a button labeled "Download Diff". Click on it. Go back to your console, create a new branch - make sure to create it based on master, and not on a local branch - and apply the patch. Some ways are:

patch -p 1 < downloaded_diff.patch
git apply < downloaded_diff.patch

Recompile the game, check if the patch does what it promises etc. Once you're done, on website, click on the Review button.

IMPORTANT: DO NOT use the Ship It feature, unless you have push access to the repo, unless we know that your codebase knowledge is one of the biggest from the project, or if you were explicitly set as a reviewer on the People field of the request. Unless you make at least one of these, DO NOT use the Ship It feature. Thanks.

Once you've written your thoughts, click on OK and then on "Publish Review". Done!

Getting help

Here are three ways to get help:

  1. Asking on IRC. We will be glad to help!
  2. Reading manuals. Hey, they exist for a reason!
  3. Searching on the internet. Most efficient of all!

Thanks for contributing to FreedroidRPG!