crawl-common 2:0.13.1-1 / usr / share / crawl / docs / develop / process.txt

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.