Contributing to Pygame Zero =========================== .. highlight:: none The Pygame Zero project is hosted on GitHub: https://github.com/lordmauve/pgzero .. _report-issue: 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). .. _`Github issue tracker`: https://github.com/lordmauve/pgzero/issues How to do a pull request ------------------------ You can make changes to Pygame Zero by creating a pull request. It's a good idea to :ref:`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: .. __: https://help.github.com/articles/creating-a-pull-request/ 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. .. _`Github page for Pygame Zero`: https://github.com/lordmauve/pgzero 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 For example: python3 -m pgzero examples/basic/demo1.py How to run tests ---------------- The tests can be run with python3 setup.py test .. _translating: 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. .. _reStructuredText: http://www.sphinx-doc.org/en/master/rest.html .. _`translation guide`: https://docs.readthedocs.io/en/latest /localization.html#project-with-multiple-translations .. _`pgzero issue tracker`: https://github.com/lordmauve/pgzero/issues/new .. _`repository ZIP file`: https://github.com/lordmauve/pgzero/archive/master.zip .. __: https://docs.readthedocs.io/en/latest/getting_started.html#import-your-docs 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.