Before continuing, please make sure that you have read our Code of conduct.
This is a general guide for those who wish to contribute to the Lass game development kit and other related projects.
These projects are free software. That means that we encourage you to modify and share them as you wish, and to collaborate with us on their development in whatever ways you are able to.
There are several ways you can contribute to our projects:
- File an issue
- Comment on an issue
- Complete an issue
- Contribute financially
Gaining Contributor status¶
As the site guide states, you will need an account to use features like filing issues, adding comments, or editing wiki pages. Your account level needs to be Contributor or higher in order for your contributions to be visible to all users without manual approval.
You can gain Contributor status by filing an approved issue, submitting a patch, or simply emailing decky (at) lassgdk.com and telling us what you'd like to contribute.
File an issue¶
An issue is a brief report detailing a potential improvement for a project. Examples of improvements include a bug or typo fixes, new features, new tests, and code refactoring.
Issues are not meant for personal assistance or troubleshooting. If you need help with Lass, email decky (at) lassgdk.com instead.
Please search through existing issues first to make sure that the issue you want to file isn't already listed. For technical instructions on browsing and filing issues, check out this guide.
You should try to fill out every field on the "New issue" form, even if they're not required. Here is a list of fields used by all projects:
- Subject: a descriptive title for the issue. This should be a short sentence describing what work needs to be done (e.g., "Replace tabs with spaces in bin/lasspm", "Write tests for TextRenderer").
- Description: use this space to describe the issue with as much helpful detail as possible. If the issue is regarding a software bug, list the steps that must be followed to reproduce the bug, and give details regarding your software environment (i.e., operating system, Python version). Screenshots are great too. If you have any ideas or suggestions on how to complete the issue, even if you aren't certain about them, feel free to share them.
- Bug: if the issue describes a software bug or typo, check this field.
- Private: if the issue is marked as private, only Administrators and Managers will see it. Note that you will only see this field if you have Contributor status or higher; unapproved users' issues will always be private until approved. This field is on by default and it's pretty easy to miss, so don't forget to turn it off unless the issue contains sensitive data or has serious security implications.
The following fields are used by Lass:
- Components: the parts of the code base that the issue pertains to. You can select multiple components by holding down the control or command key while clicking on each component. Here are the possible values:
- examples: relates to the example projects in lass/data/examples/.
- lua library: relates to the Lua libraries in lass/data/lua/5.1/.
- lua test: relates to the Lua unit tests in lass/data/tests/.
- python library: relates to the "lass" Python package. This includes all contents of the lass/ folder, except those mentioned above.
- python test: relates to the Python tests in tests/ (currently not implemented).
- scripts: relates to the executable scripts in bin/.
- tracker: relates to some aspect of the Lass Redmine tracker, such as the wiki or other issues.
- Target version: the version of Lass that this issue is affected by. Currently, the only version is v0.1.
After you file¶
If you have Contributor status or higher, your issue will be approved automatically and, if public, viewable by all users. Otherwise, your issue will be hidden from the general public until it is manually approved by a Manager or Administrator. As long as your issue is not spam, abuse, malformed, or a misuse of the issue filing system (e.g., a request for technical support), we will probably approve it.
After your issue is approved, it will be left open for others work on, unless an Administrator or Manager finds a reason to close it prematurely. The issue may be closed in such a manner if it is already covered by an existing issue, if it describes a bug that cannot be reproduced, if it is incorrect or invalid, or if there is consensus that it is not worth pursuing.
Filing an issue that is approved is grounds for receiving Contributor status, even if the issue is closed prematurely.
Comment on an issue¶
We welcome any insight or findings you have regarding existing issues that you think could be helpful. If you have an account with Contributor status, you can post public comments (called "notes") on issues. Check out this guide to find out how.
Complete an issue¶
Most issues will require a patch to be written in order to be completed. A patch is an update or fix for a project. If you want to submit a patch, you will need to do so through GitHub's pull request system.
The source code for all of our projects can be found on our GitHub page. Thus, to write and submit a patch, you will need a GitHub account, and basic familiarity with the Git version control system and the command line. You should know what it means to "fork" and "clone" a repository—read GitHub's guide if you don't.
Choosing an issue to work on¶
A project might have many open issues, so looking at them all at once might get overwhelming. As stated above, you can use filters to narrow down issues. Most projects will have a list of common filter queries in the sidebar (navigation menu on mobile).
Here are some more tips for picking an issue:
- Issues that are marked "Good first patch" are great for beginners to our projects.
- Issues for larger projects, such as Lass, will have a "Components" field detailing which parts of the project the issue concerns. This allows you to pick the issues that are most relevant to your interests and skills. For example, if you want to work on Lass and you really like working with Python, you should look for issues marked "Python library" or "Python test".
- Don't be discouraged from working on an issue just because it says "low priority". If it's open, then it needs fixing no matter what its priority is.
- Look for issues that are not assigned to anyone. Generally, issues are grouped by assignee, with unassigned issues at the top of the list.
- If you're interested in an issue, check the comments to make sure that no one has claimed it. If it's been more than a few weeks since anyone has commented on it, ask if it's still being worked on.
Once you've done the above and found an issue you're interested in, let us know that you want to work on it. If you have Contributor status, that's as simple as leaving a comment on the issue. If you don't have Contributor status yet, email decky (at) lassgdk.com instead.
Setting up your Git environment¶
- Create a fork of the repo you want to work on.
- Clone your fork.
Add a remote reference to the original repo. For example, if you are working on Lass, the command would be:
git remote add upstream https://github.com/lassgdk/lass.git
If the issue is for the most recent version of the project, and
git statustells you that you are on the "develop" branch, skip to the next step. Otherwise, you will need to switch to the correct branch for the version by issuing these commands:
git checkout tags/VERSION_NAME.0 -b VERSION_NAME git pull --rebase origin VERSION_NAME
Replace "VERSION_NAME" with the word "develop" if the issue is for the most recent version of the project. Otherwise, replace it with the correct version name. You can see a list of the version names on the GitHub page for your fork, under "Branches".
Move to a new branch using this command:
git checkout -b MY_BRANCH
Replace "MY_BRANCH" with the name you want to use for your branch. (Make sure it isn't taken.)
You should be good to go now!
Please read our brief style guide before proceeding with your patch.
Commit often. In most cases, if you can't summarize the changes you made for a commit in a single-clause sentence, you aren't committing often enough.
Your commit message should begin with the phrase "Issue #XX:", with XX replaced with the number of the issue you're working on. Here is an example.
Most commit messages are only one sentence, but some might be longer. What's important is that the first sentence be a good summary for anyone skimming through it.
If the project contains tests, make sure to run them before making a commit. Read the "Testing" section of the project's README file for instructions on running the tests.
Pull from upstream often. This ensures that your changes stay up to date and makes it less likely that there will be headaches when it comes time to merge your patch.
Please use rebase when pulling instead of merge. That means
git pull --rebase upstream develop (or whatever the branch name for your version is) instead of
git pull upstream develop. We don't want to have a bunch of merge commits in our history.
If you wind up with merge conflicts after pulling and you don't know how to proceed, please send a message to a Manager or Administrator. You can ping a user by writing their username in a comment, prefixed with the '@' symbol.
Licensing, copyright, and attribution¶
You own the copyright to anything you produce for your patch. By submitting your patch to us, you agree to publish your work under a license that is compatible with the license of the project you're submitting to. Please make sure you understand the terms of the project license before submitting your patch (ask us any questions you have!).
Because our projects use free/libre software licenses, by agreeing to these terms you give us the non-exclusive right to distribute your work in whatever way we wish, for commercial or noncommercial use, as long as we follow the license. "Non-exclusive" means that you retain the right to do the same.
If your patch is accepted, we will ask you if you would like to be credited as a contributor wherever we list contributors for that project, such as in our documentation or AUTHORS.md files. We will not do so until you give us your consent and the name you want to be attributed by. Regardless, keep in mind that a public record of your contributions will exist in the project's commit history.
Submitting your patch¶
When you feel that your patch is ready for review, you should submit it via a pull request. Here are the steps to follow:
- Make sure that there aren't any uncommitted or unpushed changes on your custom branch.
- Go to the GitHub page for the original project (not your fork) that you want to submit your patch to.
- Click on "Pull requests".
- Click on "New pull request".
- Click "compare across forks".
- Set the head fork to the original project, and the head branch to the correct branch for the version you're working on. Set the base fork to your fork, and the base branch to the custom branch you've been working off of.
- Give your pull request a title. The title should begin with the phrase "Fixes #XX", with XX replaced with the number of the issue you're working on.
- In the pull request description, ping one of the Administrators or Managers listed as watchers for the issue. This person will review your patch.
- Click "Submit".
After submitting, your patch will be reviewed. If the reviewer thinks the patch could use more work, they'll give you feedback for how to proceed. Once it looks finished, we'll merge it!
If you want to help us out financially, one way is by buying our music:
You could also donate directly to Decky (coss (at) cosstropolis.com) or Nikki (nikkicubed (at) gmail.com) via PayPal.
In the past, we have experimented with monthly crowdfunding to raise money for Lass. If you would be interested in seeing such a campaign again, please let us know. We would love the opportunity to work on Lass full-time!