Contributing to Pygame Zero

The Pygame Zero project is hosted on GitHub:

Reporting an bug or request

You can report bugs, or request features that you think should be in Pygame Zero, using the Github issue tracker.

Here are some things to bear in mind before you do this:

  • It might not just be you! You should check if someone has already reported the issue by searching through the existing issues - both open and closed.
  • The developers need to know what version of Pygame Zero you are using, and what operating system you are running (Windows, Mac, Linux etc) and version (Windows 10, Ubuntu 16.04, etc).

How to do a pull request

You can make changes to Pygame Zero by creating a pull request.

It’s a good idea to report an issue first, so that we can discuss whether your change makes sense.

Github has help on how to create a pull request, but here’s the quick version:

  1. Make sure you are logged into Github.

  2. Go to the Github page for Pygame Zero.

  3. Click “Fork” to create your own fork of the repository.

  4. Clone this fork to your own computer:

    git clone git@github.com:yourusername/pgzero.git
    

    Remember to change yourusername to your Github username.

  5. Create a branch in which to do your changes. Pick a branch name that describes the change you want to make.

    git checkout -b my-new-branch master
    
  6. Make the changes you want.

  7. Add the files that you want to commit:

    git add pgzero
    
  8. Commit the files with a clear commit message:

    git commit -m "Fixed issue #42 by renaming parameters"
    

    You can do steps 6 to 8 as many times as you want until you’re happy.

  9. Push the commit back to your fork.

    git push --set-upstream origin my-new-branch
    
  10. Go to the Github page for your fork, and click on the “Create pull request” button.

Development installation

It’s possible to create a locally-editable install using pip. From the root directory of the checked out source, run:

pip3 install --editable .

The installed version will now reflect any local changes you make.

Alternatively, if you don’t want to install it at all, it may be run with:

python3 -m pgzero <name of pgzero script>

For example:

python3 -m pgzero examples/basic/demo1.py

How to run tests

The tests can be run with

python3 setup.py test

Helping to translate the documentation

Pygame Zero’s APIs will always be English, but we can bring Pygame Zero to more users around the world if the documentation is available in their language.

If you are fluent in another language, please consider contributing by translating all or part of the documentation.

The documentation is written in reStructuredText, which is a text-based markup language for technical documentation. As much as possible, the existing formatting should be preserved. reStructuredText isn’t too difficult once you get used to it.

Creating a translation is done by creating a separate repository on Github with a copy of the documentation, rewritten (at least in part) into the language you would like to support. One advantage of this is that you can work on translations at your own pace, without having to submit pull requests back to the pgzero project itself. Please see the translation guide on Read The Docs for details.

If this sounds like something you could tackle, here’s how you might go about it:

  1. First, open an issue on the pgzero issue tracker. You should search for an existing issue covering the translation you want to do, before opening a new one. This will help ensure that you don’t do translation work that has already been done by someone else (perhaps you can collaborate instead).
  2. Create a new Github repository under your user, called pgzero-language, eg. pgzero-spanish if you’re going to translate into Spanish.
  3. Clone the repository to your own computer.
  4. Download the Pygame Zero doc/ directory and commit it in your project. You can do this by extracting them from repository ZIP file. You only need the doc/ directory from the ZIP file. You can delete the other files.
  5. Now, work through the .rst files in the docs directory, translating, using your preferred editor. You should commit regularly, and push your commits to Github.
  6. Post a link to your repository as a comment in the Github issue you created in step 1. You can do this as soon as you have some progress to show; this will help people collaborate with you on the translation if they are interested.
  7. Set up the documentation to build on Read The Docs. Again, post a comment on the Github issue when you have this working.
  8. We can then link up the new, translated documentation with the Pygame Zero documentation.

Note that Pygame Zero will have updates, and the documentation will be changed accordingly. Using Git it is possible to see a diff of what changed in the English documentation, so that you can make corresponding changes in the translated documentation.