This document is about the development process of Dungeon Crawl Stone Soup. It aims to help people interested in contributing to the project to do so. Stone Soup, by its very nature, is a community-driven project. Participation is valued, wanted, and appreciated, and indeed, is what Stone Soup thrives on. Development communication channels ---------------------------------- The official development channel is the mailing lists crawl-ref-discuss on SourceForge. Additionally, a Mantis issue tracker and a Dokuwiki wiki are used at http://crawl.develz.org/mantis/, and there is an IRC channel, ##crawl-dev, on Freenode. Mailing lists ------------- crawl-ref-discuss is where most of the discussion about the project, game design and so on takes place. The mailing list is open to subscription and the archives can be read freely. For new posters there's a moderation process where the first posts are approved to be not spam/otherwise inappropriate before the e-mail address is approved. There are also two other non-discussion mailing lists: crawl-ref-commits and crawl-ref-builds. crawl-ref-commits generates automatic summary messages of code changes, and can and should be used for reviewing commits. Commit messages also document development and decisions. People with new commit access will be on moderation on c-r-c, but their messages will be approved and they will be added to the list when the administrator(s) get around to it. The replies to commit mails should be posted to crawl-ref-discuss. crawl-ref-builds generates automatic summary messages from Crawl BuildBot. Again, the replies should go to crawl-ref-discuss. There is a deprecated mailing list called crawl-ref-devel. It has been used e.g. for deciding about granting commit rights. Currently, e-mails directly to devteam members are used instead. They are sometimes used for other decisions as well. The mailing list archives can be browsed, and the lists themselves joined at http://sourceforge.net/mail/?group_id=143991 The CDO tracker and wiki ------------------------ The Mantis issue tracker is used to track bug reports and to post code, graphics and vault submissions (patches). It is also used by the developers to publish and track "Implementables" - desired features, that will not immediately be implemented by a devteam member. If you are looking for something to code, you can check the tracker for bug reports and implementables, announce you are working on them, and submit patches when ready. Developers can assign issues to themselves or other developers. Self-assignment is used if the developer is working on the issue. Assigning to someone else is used if something's in their area of expertise or assigner wants their opinion. Either way, the reason for changing the assignment should be mentioned in the message. The wiki is used to leave feedback, make and discuss features suggestions, and otherwise store and edit content and documentation as necessary. The general workflow is to iterate ideas and feedback over in the wiki. After a conclusion is reached, a devteam member may either commit the appropriate changes to the codebase, or posts an Implementable on the tracker for patchers. Not all the ripe ideas from the wiki are posted as Implementables, so it's ok to work on such ideas and submit patches. It may be best to ask the mailing list or the irc channel in such a case. To report issues or post comments to the tracker, or to edit the wiki, you need to register. The tracker and wiki can be browsed without logging in. Please search the tracker and wiki for similar items and duplicates before submitting a new item. IRC --- The IRC channel ##crawl-dev on Freenode is dedicated to Dungeon Crawl development. The channel is open to any participants but the discussion is expected to center on development. The channel is a bit less formal/official than the mailing list and the tracker. However, the turnaround for question is usually considerably shorter so it is usually a good place to come to if you have ideas for patches or, for instance, vaults. Also, users with +v have commit access, so if you have a patch which is ready to commit you can poke them about it. 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 at http://s-z.org/crawl-dev/ Development team structure and decision policy ---------------------------------------------- The development team consists of a large variety of people: all have commit access, and administrators have the ability to grant commit access to new people. As mentioned in the section on mailing lists, this is usually discussed privately in emails between devteam members. Administrators will make final design decisions where necessary, or where there is confusion or debate. All participation is welcomed and encouraged. From time to time there will be tensions or even clashes among developers. Minor ones (e.g. "Can we remove pizzas?") can be quickly sorted out. Resolving major ones ("Do we need the Swamp branch?", "How many gods should there be?") can often take even several releases. In these cases, only time, many words and pragmatism will help. It is crucial to remind oneself from occasionally that there are other acceptable situations apart from the own. There can be no formal rules for solving such problems, because we want neither design stagnation (i.e. adding only with mutual agreement) nor dictatorship (because other people do have good ideas sometimes, even if it's hard to believe). All developers are free and expected to commit changes on their own -- no need to ask in advance. This goes especially for features they are already introduced. For example, vault designers can and should apply changes to their vaults. However, there are cases which are less clear cut. If you are not sure about that, at least mention it in the commit message, allowing others to look into the commit and possibly comment. And it is always to okay to ask beforehand about a change. The best way to go about this is to prepare a short mail to the discussion list, mentioning the commit you are about to make, perhaps explain way, give a few option and point at the one you're about to implement if nobody objects. Waiting a day or two is probably enough -- if no one responds, either go ahead or demand replies. Stone Soup welcomes participating in the development. The difference between someone with commit access and someone without is that the former can add their changes to code (and other files, such as documentation, vaults, tiles and so on) directly. Those without need to submit patches to the Mantis tracker. See docs/develop/patch_guide.txt for details. There may be instances where a patch or commit has to be reverted, either due to design issues, or due to a bug. Please do not be offended if this occurs. While patches and ideas are welcomed, please also understand that these may (and likely will) be altered to fit better into the overall design of Stone Soup. Giving commit rights to people ------------------------------ A development team member may suggest to others in a private e-mail that commit rights are given to a contributor. As other members agree (or there are no objections), commit rights are usually given, and this is then announced. Generally, if a contributor supplies a substantial amount of patches of good quality (i.e. patches don't break things, don't need cleaning up before committing and are in line with the general direction of the development), it makes sense to give them commit rights.