We welcome and appreciate community contributions, and contributions that meet our standards are accepted for all areas of the game. You can fix typos and standing bugs; optimize a process; submit a new vault; create a new (or improved) tile for a monster, item, or dungeon feature; create a new item or spell; or even create a new species, monster, or god. This document is a guide to the process of making a contribution and has pointers to use during development and discussing.
Please note that since crawl is an entirely volunteer project, and the development team's available time fluctuates. So the time it may take us to evaluate contributions will vary. In addition, not every contribution will be accepted. Also keep in mind that the more significant your contribution is, the more scrutiny it will receive! Small bugfixes and minor vaults are more likely to be approved than not, but a new species or new god will undergo a thorough review process by many members of the dev team if it seems if it will be merged into the game.
Most discussion happens nowadays via IRC at the #crawl-dev channel on Libera.
This is where casual discussion and review happens. If you have a quick
question about design or coding or whatnot, this is where you'll get the best
turnaround time.
Users with +v are members of the devteam and have commit access. Developers often discuss what they are working on on the channel and request comments before commits. Therefore the channel is logged to archive discussion and decisions made there. The archive can be found here:
http://s-z.org/crawl-dev/
For proposals that would have a significant impact on gameplay, it's good to get feedback and discussion from experienced crawl players. One place to start is the Game Design Discussion board (GDD) on the official Tavern forums. Please follow the GDD discussion guidelines posted at the top of that forum.
For planning and brainstorming, there is a Doku development wiki where anyone can register to create and edit wiki pages. This wiki is more useful if you're working on a larger project that's in need of outside ideas
An alternative to the Doku wiki is github wiki system. You can fork the crawl repository if you haven't done so already and create wiki pages in that fork. By default, github users who aren't collaborators for your repo can't edit wiki pages. You can allow other github users to edit your repository's wiki without allowing them commit access to the repository itself by going to the Settings tab of the repository and unchecking the box "Restrict editing to collaborators only". Finally, you can also add specific github users (such as a dev you are working with) to your repo's list of collaborators, which also grants them commit access in your repo.
Before you start development, you'll want to look through the game's documentation (in docs/develop/, where this file is located) for guidelines, as well as compare your ideas and work against previous changes to Crawl and current Crawl features.
If you're coding, then you'll want to read the setup process outlined in docs/develop/git/quickstart.txt as well as set up an IDE or editor to make your changes to the Crawl codebase. Crawl is coded primarily in C++, with Lua used for level layout and vault definitions as well as for some aspects of controlling the client. The WebTiles server is coded in python2 and uses the Tornado framework (version 2.3 to 3.x; modern Tornado will not work). The WebTiles browser client is written in JavaScript using the jQuery and other JS libraries. The local Tiles version uses the SDL2 graphics library.
If you're doing tiles art, or splash screen art, then it's recommended to look at previous artwork and try to match the general style presented there. This is not a hard-and-fast rule, and clear improvements are always welcome.
If you have questions for how to progress further, then feel free to pop into
#crawl-dev and ask for help. Responses are reliant on dev availability and
knowledge/expertise.
The normal way to submit a contributing to crawl is by making Pull Request (PR) on github. The technical parts of this process are fairly standard for any github-hosted project. We also will accept patches uploaded to mantis, but would prefer this to be limited to small changes like vaults or artwork.
- You clone the crawl repository and make your changes in a branch on your
cloned repository.
- Observe the code style guidelines and commit message style guidelines (72 char width, line between title and body, bug # or reporter in title).
- Include a commit message with meaningful content for every commit. It's fine if a PR comment duplicates this, but the priority for explaining the changes should be in the commit messages themselves.
- You open a PR in the main repository based on your branch.
- Some member(s) of the devteam reviews the commit, probably asking some questions and making some suggestions for changes. This happens at the pace of devteam availability, which can fluctuate. Be prepared to check in with devs from time to time to ask about your PR.
- You make some changes to your branch and push, which will automatically
update the PR.
- Devteam members won't make changes in a PR branch, and force-pushing to your fork's branch is fine. However, in some cases where changes were requested it can be useful for us to see the commit sequence (and some devteam members prefer this for newer contributors). There's no requirement to rebase changes.
- In branches we generally prefer rebasing on master rather than merge commits. However we can rebase your branch ourselves when merging.
- Steps 3-4 may repeat.
- If all goes well, a devteam member merges the PR. This will typically involve a rebase, and the devteam member may tweak some details of the commit(s) at this time, and potentially squash commits.
- It is often a good idea to chat about even small changes with some devteam members, especially if you are new to the dcss codebase or to game design. The best place for this is in the #crawl-dev IRC channel on Libera.
- PRs that have good commit messages and conform to style guidelines tend to get merged faster, all things being equal. A very common mistake is to put a lot of text in the PR first comment, and leave the commit message blank. Usually, this will require a devteam member to manually copy information from the PR and reformat for a commit message, slowing the process.
- PRs that fix bugs are very likely to get merged in some form (though you may receive suggestions for alternative strategies for fixing the bug).
- PRs that change gameplay in particular need to be carefully thought out, and
ideally, discussed with members of the devteam ahead of time.
- Think carefully about what you want the change to accomplish, and provide justification in the commit message(s).
- Think carefully about whether a change might lead to something surprising being optimal.
- Think carefully about how the change will be received by both extremely strong players and by new players.
- If the change is in response to a strong opinion or reaction that you have to some aspect of crawl, consider whether your opinion is likely to be universal or obvious. It's best if you can be dispassionate about proposed changes.
Community members often talk about "the devteam" as if it's a single entity with one specific set of plans, beliefs, aesthetics, etc. This view is not correct, and so you should be aware that one response you get to a proposal (be it positive or negative) doesn't necessarily indicate the views of the whole devteam, or preclude an opposite response from some other devteam member.
We do welcome major contributions that introduce something substantially new (e.g. gods, species, UI overhaul, etc), and many contributed patches along these lines have made it in to the game. However, many haven't, and the bar for getting such a change into a stable release of DCSS is high. If you would like to make such a change, you should go into it prepared for the possibility that it won't make it, and that if it does, it will make it in a substantially revised (perhaps unrecognizable) form. You should also be prepared for the contribution to involve a process, with potentially many revision cycles.
If your goal is getting something into stable (see below for a definition of "stable"):
- We generally recommend against a new god, species, role, branch, or anything of this scope being your first contribution.
- You will need to be responsive in a positive way to feedback, including critical feedback.
- You will need to be prepared for the latter parts of the acceptance process being rather detail-oriented, making sure all the UI elements work as expected, checking all the special cases you can think of, etc. If you don't do this part some devteam member would need to, which will substantially slow, or even prevent, acceptance into the game.
- Major contributions will very much be tied to the alpha/beta/release cycle for the game: they are very unlikely to be accepted close to a release target. (This can go for smaller contributions as well, if they are likely to require a fair amount of testing for one reason or another.)
N.b. this is open-source software, your goal doesn't have to be getting a change into stable! Many devteam members are happy to talk to fork developers, or people just developing something for fun.
One potential path for a new major-ish contribution (and some contributions from inside the devteam) is branch -> experimental -> trunk -> stable.
Branch: a git branch that has some set of proposed changes on it. A github PR is a special kind of branch.
Experimental: sometimes server operators are willing to install a branch in the repository as an additional playable version of the game in order to test out a large feature. Games in experimentals are indexed by Sequell and do get a fair amount of play, but much less than trunk. All that is needed to have an experimental version is a branch that doesn't crash too much and the goodwill of a server operator. Experimental branches are generally used for developing large features that have some initial acceptance from the devteam but that need extensive play-testing and would be invasive to test in trunk due to not being in a finalized state.
Trunk: the current unstable testing ground for new features or changes to crawl; if you have a PR merged it will go into trunk. Many online players play trunk, so something being tested in trunk receives wide exposure. A feature being in trunk is not a guarantee that it will make it into stable, and anything complicated enough will usually need iteration in trunk. Sometimes features that do make it are trunk-only for multiple stable release cycles.
Stable: stable versions of crawl are released on a ~6month cycle, coinciding with a tournament; each stable release takes the form of a branch off of trunk at the time of release, and will receive mainly bugfix patches from that point. Online players play both stable and trunk, and offline players predominantly play stable.
Firstly, thank you for helping to improve and expand Crawl! After your patch is included, then it becomes part of Crawl, and as such will come under the jurisdiction of the dev team. Your contribution may be altered, sometimes even significantly, from what you originally envisioned for it. Sometimes this means a total rewrite of the code, other times it means an overhaul of how it works, and occasionally it might end up being removed one day.
This is part of the natural process of developing and maintaining Crawl, to keep its design healthy and long-lasting. It won't be a reflection upon you or your ideas if it is altered.
Of course, most of the time, especially when they were originally in line with general Crawl design philosophy, contributions and additions to Crawl won't be significantly altered.