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

Dungeon Crawl: Stone Soup, by its very nature, is a community-driven project.
Participation is valued, wanted, needed, and appreciated. Without community
contributions, this project is little more than a stone in a pot of water.

This document outlines the development process of Dungeon Crawl Stone Soup, and
makes it clear what steps contributors will take to submit their changes and
updates to Crawl, as well as what to expect from the process and, potentially,
after their contribution is merged into the game.

Where do I talk about the game?
-------------------------------

The official development channel is the mailing list crawl-ref-discuss (C-R-D)
on SourceForge: https://lists.sourceforge.net/lists/listinfo/crawl-ref-discuss
This channel is primarily for longform and semiformal discussion on development.
Anyone can subscribe to this channel, but for new posters there is a moderation
process before they can begin contributing to the mailing list.

The archive for C-R-D can be freely viewed here:
    http://sourceforge.net/mail/?group_id=143991

There is a dev wiki at https://crawl.develz.org/wiki/doku.php. This is
where planning for the current and future versions is held, as well as writeups
of larger and more comprehensive projects and goals for the game. If you are
planning something complex, or want to collaborate with multiple other people on
your idea, the wiki may be helpful.

There is also an IRC channel, where most discussion happens nowadays, at
##crawl-dev on Freenode. 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/

Finally, there is the official discussion forum, the Tavern, hosted on CDO at:
    https://crawl.develz.org/tavern/
The Game Design Discussion forum is where you can receive feedback from other
Crawl players, and occasionally a dev, on your idea proposal.

What can I contribute to Crawl?
-------------------------------

Lots of things! 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 artefact; or even create a new species, monster,
or god.

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.

How do I develop a contribution? What references do I use?
----------------------------------------------------------

You'll want to look through the game's documentation (in docs/develop/, where
you already are) 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
/crawl-ref/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 the occasional Lua.

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.


How do I submit a contribution to Crawl?
----------------------------------------

There are two methods, to submit an issue through our Mantis tracker:
    http://crawl.develz.org/mantis/
or a pull request through our GitHub page:
    https://github.com/crawl/crawl

I've submitted my contribution. Now what?
-----------------------------------------

When a member of the dev team has time (devs work on a volunteer basis), they
will review your submission to see if it fits with the general design guidelines
for Crawl and passes muster in terms of functionality and quality. For many
small submissions, that's all that it takes; should everything check out, it'll
be merged into the game.

Other patches will receive requests from a dev to improve it further, or to
fix problems with it. Significant changes (species, gods, etc) will frequently
require cooperation with the dev team to massage it into something more in line
with Crawl design guidelines.

Sometimes, your contribution will be rejected. In this case the submission will
be closed, often with an explanation of why it won't be included. This can be
painful -- you spent time and effort on this, after all -- but it should never
be taken personally. Having some of your contributions rejected does not
necessarily mean that your future submissions will be rejected.

My contribution made it into the game! What can I expect?
---------------------------------------------------------

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.