This document shall give you an overview of how you can contribute to the project. It is split up in these parts:
This section includes a collection of ways to contribute. The purpose of the different issue templates is to guide contributors and to allow synchronization with other developers.
Please see if the bug was reported before by searching the issue tracker for some key words you would say. In case it was, you can collaborate, leave a comment and get into discussion.
To report a bug, please open a new issue following this issue template. A bug might be unexpected behavior or a clear violation of design principles.
Please see if the feature was reported before by searching the issue tracker for some key words you would say. In case it was, you can collaborate, leave a comment and get into discussion.
If you have a new idea about how to improve the game, please open an issue for your feature request.
When the game starts, you can choose your game character from a menu. You can add your own character to this menu. Please open an issue which can guide you further on how to add a character.
We have an issue tracker which lists issues of this game. You can choose to comment on an issue that you like to work on it. Please share your progress as soon as possible by creating a pull request. You do not have to ask for permission to solve an issue. You can just do it. To reduce duplicated work however, please coordinate in the issue with other people. If you do not get a response, feel free to solve the issue yourself.
In case the issue is easy and you are an advanced programmer, you can use the issue to guide new contributors by choosing not to solve it but telling that you like to help out and giving hints for a solution.
You can use the issue template with the label good first issue to indicate that this issue is suitable for beginners. Also, please describe in the issue what steps are to be taken to solve it (Implementation Plan) and what a solution looks like (Closing Criteria).
If you like to help improve the game or a bug caught your eye and you like to fix it:
- Please visit the issue and leave a comment that you like to work on it.
- See if someone else opened a pull request. If so, you can choose to comment that you like to cooperate.
- If there is no pull request by other people within a day, feel free to create your own pull request within one day.
If you create a pull request, you do not need to solve all problems at once. We like little steps more because they are easier to understand. Please follow the pull request template or change it.
To inform other people about your work and to enable them to use our work, consider to create pull requests as soon as possible, after the first small commit.
Contribution is made easy through well documented APIs. You can find documentation on how to contribute here:
- CONTRIBUTING.md summarizes ways to contribute and motivates them
- README.md includes old documentation on how to go about contributions
- documentation directory includes the files used to document how the labyrinth can be modified.
Please open an issue to let us know where to improve the documentation.
You can add new of these entries to this section. Please evaluate your idea like this:
- If it can be done once and is completed, it is an issue, not a task.
- If it can be done endlessly and is done once, it is a task.
- If you mix both in a task, think about adding a task enablement issue.
Then, open a new issue.
To make the game more interesting, please add a place which can only be entered if something else was done before, e.g. a door with a key to find, a troll and a meal to prepare, a river and a boat to build, ... .
To do this, please open a dependency issue. You will be guided from there.
To make the game more interesting, please add background music. Please follow the issue template for adding background music for doing so.
You can cooperate on pull requests with other contributors. You can use techniques like pair programming or collaborate together on branches of your forks. You can attribute a pull-request also to other people who helped you out or submit a pull-request where you and an other person contributed together.
You can comment on an existing issue that you like to cooperate with specific people or ask in the chat if anyone would be interested in cooperating.
When you enter a tile, the game can play sounds. Please follow the issue template for tile music to add music to certain tiles on entering. Consider that the music should be your own.
You can add small parts of the labyrinth for people to walk through it. Please open an issue if you like to create a tile to help us help you customize the game.
The labyrinth not only contains computer-generated tiles but also tiles draw by hand. Please open an issue if you like to create a hand-drawn tile to track the progress.
Although you see only one level, you can reach the goal tile of this and other levels to switch between the levels. You can add new levels to the labyrinth. Please open an issue for adding a new level which will guide you through the process.
If you like to design a huge part of the labyrinth to one topic, you can do that. We call it a theme. Currently, we have the a theme of rooms and doors. There could be more themes of your imagination: pipes, riffs in the sea, bridges, Minecraft, ... This tasks takes several hours, maybe days. In the end you have an own labyrinth theme. If you like, you can embed it or create a new level for it.
Please open an issue to let us know about the progess and invite others to collaborate and give feedback.
Tiles may consist of several parts. All of them can be animated: footsteps walking around, birds flapping, light bulb flickering, ... You can choose to create a new tile and animate it or animate an existing tile either by modifying it or copying.
Many tiles use the same walls. You can make this game more divers by creating different kinds of walls. Please open an issue to share your ideas and let us know.
To promote the game and draw new contributors, you can create a promotional video about the game. Please follow the guidelines to create this video.
Improving the code quality makes it easier to add new code which is flawless. This is also a traning for you to write good code and to make a meaningful contribution to existing code while learning it.
If you like to improve the code, please open an issue to let us know what you are working on and coordinate the effort.
We strive to have a pleasant user experience by providing a uniform design as stated in the UI Guidelines. If you find a mismatch or like to improve the UI, please open an issue for this and describe the bug.
- Write clear meaningful git commit messages (Do read http://chris.beams.io/posts/git-commit/)
- Make sure your PR's description contains GitHub's special keyword references that automatically close the related issue when the PR is merged. (More info at https://github.com/blog/1506-closing-issues-via-pull-requests )
- When you make very very minor changes to a PR of yours (like for example fixing a failing travis build or some small style corrections or minor changes requested by reviewers) make sure you squash your commits afterwards so that you don't have an absurd number of commits for a very small fix. (Learn how to squash at https://davidwalsh.name/squash-commits-git )
- When you're submitting a PR for a UI-related issue, it would be really awesome if you add a screenshot of your change or a link to a deployment where it can be tested out along with your PR. It makes it very easy for the reviewers and you'll also get reviews quicker.
- Tip for deployment - You can create the deployment link for the Labyrinth app to check how your commited changes look, you can view the deployed site on this link: http://rawgit.com/YOUR_USERNAME/labyrinth/master/index.html
- In HTML files, there should be no spaces before the html, head and body tags. All the nested tags of HTML have to be indented with 2 spaces. Same goes for CSS and JavaScript. Please follow this in order to keep the indentation style consistent.
- Please try to avoid obvious comments. Commenting should be done only when it's necessary.
- Follow the DRY(Don't Repeat Yourself) principle. The same piece of code should not be repeated over and over again.
- When you file a feature request or when you are submitting a bug report to the issue tracker, make sure you add steps to reproduce it. Especially if that bug is some weird/rare one.
- Please have a look if someone else suggested something similar and see it a new issue is necessary.
- Please follow the issue template as it focusses on the motivation and how life and the game is improved. This can not be reflected by code as well.
- Before you join development, please set up the project on your local machine, run it and go through the application completely. Press on any button you can find and see where it leads to. Explore. (Don't worry ... Nothing will happen to the app or to you due to the exploring 😉 Only thing that will happen is, you'll be more familiar with what is where and might even get some cool ideas on how to improve various aspects of the app.)
- If you would like to work on an issue, drop in a comment at the issue. If it is already assigned to someone, but there is no sign of any work being done, please free to drop in a comment so that the issue can be assigned to you if the previous assignee has dropped it entirely.
Do read the Open Source Developer Guide and Best Practices at FOSSASIA.
Usage of CDNs and other online hosts for assets used in the Labyrinth is not recommended. We want users to be able to play the game without an active internet connection. CDNs slow down the page by collecting analytics data. And who wants bots monitoring what you do?
Make sure you keep them in their respective folders in the Github Repository.
We recommend you add code and work which you did yourself. By adding this code to the repository, you put it under the AGPL license.
If you embed other work, you need to be compatible with the current license. Licenses compatible are e.g. MIT, GPL, AGPL, LGPL, BSD. In almost no case is it legal to just copy the code/files without license.
- Embedding MIT: You need to keep the license close to the code:
- CSS/HTML/Javascript: embed it into the code, it is not that long
- binary files e.g. fonts: create a file with the same name next to the binary file with
.licensein the end and copy the license in there.
- Stackoverflow: Link to the answer or question.
- ... append in the future.