Notes for Xonotic Map Manager Contributors
Learning Xonotic Map Manager
The fastest way to learn is to read the documentation.
Before filing an issue
Reporting a potential bug? Please read the "How to file a bug report" section to make sure that all necessary information is included.
Contributing code? Be sure to review the contributor checklist for helpful tips on the tools we use to build Xonotic Map Manager.
Create a GitHub account.
Install xmm in development move, preferably inside of a virtual environment, see the README for details.
Keep xmm current. Keep the repository up-to-date and rebase work-in-progress frequently with
git pull --rebaseto make merges simpler.
For more detailed tips, read the submission guide below.
How to file a bug report
A useful bug report filed as a GitHub issue provides information about how to reproduce the error.
- Before opening a new GitHub issue:
- Try searching the existing issues.
- Try some simple debugging techniques to help isolate the problem.
- Try running the code with the debug log settings
If the problem is caused by a package in
requirements.inrather than core xmm, file a bug report with the relevant package author rather than here.
When filing a bug report, provide where possible:
- The full error message, including the backtrace.
- A minimal working example, i.e. the smallest chunk of code that triggers the error. Ideally, this should be code that can be pasted into a REPL or run from a source file. If the code is larger than (say) 50 lines, consider putting it in a gist.
- The version of xmm as provided by the
xmm --versioncommand. Occasionally, the longer output produced in
~/.xmm/xmm.logmay be useful also, especially if the issue is related to a specific package.
- When pasting code blocks or output, put triple backquotes (```) around the text so GitHub will format it nicely. Code statements should be surrounded by single backquotes (`). Be aware that the
@sign tags users on GitHub, so references to macros should always be in single backquotes. See GitHub's guide on Markdown for more formatting tricks.
There are never enough tests.
Browse through existing tests
Write your tests using pytest
make teststo run your tests
Submit the test as a pull request (PR).
By contributing documentation to Xonotic Map Manager, you are agreeing to release it under the MIT License.
Xonotic Map Manager's documentation source files are stored in the
docs/ directory. Like everything else these can be modified using
git. Documentation is built with sphinx, which uses Restructured Text syntax. The HTML documentation can be built locally by running
from Xonotic Map Manager's root directory. This will build the HTML documentation and place the resulting files in
When making changes to any of Xonotic Map Manager's documentation it is recommended that you run
make cleanto check the your changes are valid and do not produce any errors before opening a pull request.
For new functionality and other substantial changes, add a brief summary to
CHANGELOG.md. The item should cross reference the pull request (PR) parenthetically, in the form
([#pr]). To add the PR reference number, first create the PR, then push an additional commit updating
CHANGELOG.md with the PR reference number.
Contributing to core functionality or base libraries
By contributing code to Xonotic Map Manager, you are agreeing to release it under the MIT License.
The Xonotic Map Manager community uses GitHub issues to track and discuss problems, feature requests, and pull requests (PR). You can make pull requests for incomplete features to get code review. The convention is to prefix the pull request title with "WIP:" for Work In Progress, or "RFC:" for Request for Comments when work is completed and ready for merging. This will prevent accidental merging of work that is in progress.
Add new code to Xonotic Map Manager's base libraries as follows:
Edit the appropriate file in the
xmm/directory, or add new files if necessary. Create tests for your functionality and add them to files in the
Add any new files to
Add any new artifacts to
Build as usual, and do
make clean && make lint && make tests to test your contribution.
Code Formatting Guidelines
General Formatting Guidelines for Python code contributions
- PEP-8 compliance minus the ignored rules in the
Git Recommendations For Pull Requests
- Branch off
git checkout develop && git checkout -b feature/my-cool-feature
- Avoid working from the
masterbranch of your fork, creating a new branch will make it easier if Xonotic Map Manager's
masterchanges and you need to update your pull request.
- Try to squash together small commits that make repeated changes to the same section of code so your pull request is easier to review, and Xonotic Map Managers's history won't have any broken intermediate commits. A reasonable number of separate well-factored commits is fine, especially for larger changes.
- If any conflicts arise due to changes in Xonotic Map Managers's
develop, prefer updating your pull request branch with
git pull, since the latter will introduce merge commits that clutter the git history with noise that makes your changes more difficult to review.
- Descriptive commit messages are good.
git add -por
git add -ican be useful to avoid accidentally committing unrelated changes.
- GitHub does not send notifications when you push a new commit to a pull request, so please add a comment to the pull request thread to let reviewers know when you've made changes.
- When linking to specific lines of code in discussion of an issue or pull request, hit the
ykey while viewing code on GitHub to reload the page with a URL that includes the specific version that you're viewing. That way any lines of code that you refer to will still make sense in the future, even if the content of the file changes.
- Whitespace can be automatically removed from existing commits with
- To remove whitespace for the previous commit, run
git rebase --whitespace=fix HEAD~1.
- To remove whitespace relative to the
git rebase --whitespace=fix master.
- To remove whitespace for the previous commit, run
- Homepage: https://github.com/z/xonotic-map-manager
- IRC: http://webchat.freenode.net/?channels=xonotic
- Source code: https://github.com/z/xonotic-map-manager
- Git clone URL: git://github.com/z/xonotic-map-manager.git
- Documentation: http://xonotic-map-manager.readthedocs.io/en/latest
- Build Status: https://travis-ci.org/z/xonotic-map-manager.svg?branch=develop