BZFlag

Contributing

Reporting Bugs/Issues

If you find a problem with the game you can report it to our development team. If you are unsure of the source of the problem, feel free to discuss the problem on our development/support IRC channel at #bzflag on the irc.libera.chat network or on our public forums. Otherwise, you can post the issue to our BZFlag project issue tracker on GitHub. There are also separate repositories and issue trackers for the other related projects such as our websites. You will find all our official projects at our GitHub organization page.

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 master branch and creates a new topic branch called feature/betterui 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/Your_User_Name/bzflag
  3. You will be working from within the bzflag directory from now on. Run:
    cd bzflag
  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
  5. Next, check out the upstream branch you are intending to submit changes to.
    git checkout master
  6. Do not work directly in the branches that the official repository has created (such as 2.4 or master). Instead, create your own topic branch that describes the change you are trying to make. For instance, if you were trying to add an improved user interface, your branch could be called feature/betterui. Create and checkout that new branch with:
    git checkout -b feature/betterui
  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 feature/betterui
  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 master and feature/betterui below are examples, with feature/betterui being a branch off of master. 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 master
  2. Fetch upstream changes
    git fetch upstream
  3. Merge upstream changes into your fork
    git merge --ff-only upstream/master
  4. Push new changes to your fork
    git push origin master
  5. Checkout your branch you wish to merge changes into
    git checkout feature/betterui
  6. Rebase your branch against the branch it is based on
    git rebase master
  7. If there are any conflicts, you must resolve those.
  8. Push the rebased branch
    git push --force origin feature/betterui

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.

This content is maintained on GitHub. We welcome any feedback and improvements!

Give us Feedback Edit this Page