Skip to content

Contributing

Jump to bottom
blast007 edited this page Jan 4, 2019 · 9 revisions

Contributing

Getting Help

The developers hang out in the #bzflag channel on irc.freenode.net, which you can join with either a normal IRC client or Freenode's web IRC client. There you will find the main website developers: blast and allejo.

Reporting Bugs/Issues

The issue tracker can be used to report issues with the website.

Contributing Changes

With Git and GitHub, contributing to a project is reasonably easy, but we'll try to walk you through best practices. This will allow you to work on multiple independent changes at the same time, keeping them in separate "topic branches". The example below assumes you want to contribute to the redesign branch and creates a new branch called documentation/flags in your fork.

  1. You will need to fork our GitHub repository the first time you want to contribute changes. You can use this same fork for later changes. Sign in to your GitHub account, go to our GitHub repository, and click the Fork button.
  2. Now that you have a fork of our code, you need to clone it to your computer so you can work on it. Run:
    git clone https://github.com/YourUserName/bzflag.org
  3. You will be working from within the bzflag.org directory from now on. Run:
    cd bzflag.org
  4. In order to later merge changes from our official repository, add an upstream remote:
    git remote add upstream https://github.com/BZFlag-Dev/bzflag.org
  5. Next, check out the upstream branch you are intending to submit changes to.
    git checkout redesign
  6. Do not work directly in the branches that the official repository has created (such as master or redesign). Instead, create your own topic branch that describes the change you are trying to make. For instance, if you were trying to write additional flag documentation, your branch could be called documentation/flags. Create and checkout that new branch with:
    git checkout -b documentation/flags
  7. Now make changes to files and then git add FilesYouModified to stage the changes.
  8. Once you have some changes staged, you can commit those changes to your local clone. An editor will appear where you can write a message that describes the changes you have made.
    git commit
  9. Once you have one or more commits applied to your branch, you can push these changes back up to your fork on GitHub.
    git push -u origin documentation/flags
  10. You can repeat the process of editing files, committing, and pushing until you are ready to submit your changes back to the official repository. For this, you would create a pull request (known as a PR) on GitHub. After creating a pull request, you can continue to push new changes to your branch and this will update the changes on the PR. GitHub provides a page that talks about pull requests.

Keeping your fork in sync

As new changes are pushed to the official BZFlag project repositories, your fork will become outdated. The steps below will allow you to update your fork and bring in any new changes. The branches redesign and documentation/flags below are examples, with documentation/flags being a branch off of redesign. If you are working with another base branch, such as 2.4, or you want to update multiple branches in your fork, adjust as necessary.

  1. Checkout the branch name matching the upstream branch you would like to update
    git checkout redesign
  2. Fetch upstream changes
    git fetch upstream
  3. Merge upstream changes into your fork
    git merge --ff-only upstream/redesign
  4. Push new changes to your fork
    git push origin redesign
  5. Checkout your branch you wish to merge changes into
    git checkout documentation/flags
  6. Rebase your branch against the branch it is based on
    git rebase redesign
  7. If there are any conflicts, you must resolve those.
  8. Push the rebased branch
    git push --force origin documentation/flags

More Information

GitHub has some documentation and guides for forking GitHub repositories:

There are various sites with tutorials and information about using Git:

There's also an online interactive site called Learn Git Branching.

Clone this wiki locally