doc/development_process.md
Contents
A guide for new and prospective contributors, or just for people curious about how the devs understand the project to work.
This guide is intended to describe how the Cataclysm: Dark Days Ahead project is managed by the development team, and hopefully in the process, clear up common rumours and misconceptions about how it all works. In this document the term "we" is intended to mean "CleverRaven as an organization", and does not necessarily reflect the individual opinions of anyone in CleverRaven.
This document assumes you have a basic understanding how GitHub works. Please see the guide for new contributors for more info there. You might also find helpful information in the Frequently Made Suggestions doc. This guide from GitHub also gives a decent run-down of the structure of any open source project.
At its core, CDDA is a survival simulation game. The design doc outlines what we mean by this. The project is led by Kevin Granade, who owns CleverRaven and therefore this fork of the code. As lead developer, Kevin's main job in the project is to be the last word if one is needed. Most of the time, we don't need his final arbitration to know if something is going to fit or not.1 The rest of the project's structure is organized chaos, and understanding it is daunting at first.
One of the most important concepts to understand in our project is the experimental/stable branch system.
The intention here is that if you want to play CDDA, you'll play on stable. This is a curated snapshot of the game with as few major bugs and balance issues as possible. Sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game, but we try to keep stable balanced and fun.2
On the other hand, in the experimental branch, we allow things to get broken. We often allow (trusted) contributors to mess something up, especially if the code base they're adding is a strong foundation to build on. In a volunteer-driven project, sometimes these can be slow to fix. That's why we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, but from our perspective, those people are more like playtesters, not players. It might help to understand how we process playtest feedback:
Or, Why not finish things before putting them in a public experimental release, or revert them if they're broken?
There are dozens of different good reasons. Let's look at just one, because it's possibly the most important and also the most difficult to see unless you really examine development over the long term.
Allowing things to get broken in experimental allows us to have big, ambitious projects. If we forced ourselves to keep experimental 'smooth' all the time, contributors wouldn't be free to take risks. Most of the complex things that make CDDA unique would have been almost impossible to create. We'd be less welcoming to less experienced programmers, even if we didn't want to be. In the long term we wouldn't have a better player experience to show for it, because many of our most interesting changes come about as the product of long - often years long - projects that remain in a messy state as we sort them out. This is the trick we've found that allows unpaid volunteers to develop amazing systems that would be at home in a professional game, while having only a few hours a week of their time to contribute.
Cataclysm: DDA is one version of the 'Cataclysm' source code. There are many others. Even your own branch on your own GH account is a fork, technically. The main game is often called "mainline".
This is a quick summary of the different terms we use for different groups within the project. Almost all of these terms are quite fuzzy and imprecise.
This is built from concerns we've heard from other new contributors to the project, things they wish they'd understood when starting out. Here's the most important TL;DR points:
If what you're doing is simple, chances are you don't need to worry. If you're new to the project and have big ideas for what you want to add, though, we strongly recommend you first discuss these with someone more experienced in the project. There are three good ways to do that: create an Issue post on GitHub, chat in the developer discord in the Development or CDDA-Discussion channel, or post in the discourse forum6 about your ideas. The larger the project you plan to add, the more important it is to check in first. That isn't to say big things can't get in without prior approval - it happens all the time - but it's always a bigger risk, especially if you're new.
Most PRs do get accepted. If you are the sort of person who won't really mind if you do some work and find it's going to have to go back to the drawing board, you can skip this entire document. You'll be fine. If that possibility concerns you though, reading on may help you to navigate collaborative feedback in a large and mostly unorganized community.
If you've created an issue or a discourse post and aren't getting much feedback, try reaching out on Discord as a good second measure. Be patient and give us time to spot you, but don't be afraid to be persistent. Due to the high activity on the project, stuff often slips beneath people's radars. That doesn't mean we're not interested in what you've got. It's just a side effect of it being a volunteer project where all of us have limited time to devote.
The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are pretty likely to know what's what. After them, the collaborators and moderators (people with blue or magenta names on discord) usually have a very good concept of the project direction. Anyone else can of course offer an opinion, and often have great information, but take it with a grain of salt, especially if it conflicts with the above. We often get well-meaning people speaking with confidence about elements of the project they don't fully understand yet.
On GitHub it can be a little harder to tell who is who, and we don't really have a way around that. If you see somebody merging PRs, closing issue posts, or adding labels to issues and PRs though, that's a person who probably has a higher level of trust in the project. There's also a "member" badge on the upper right of github posts, like this:
If a person has a "member" badge there, it usually means they speak with some authority. However, we all have different areas of the project we know better than others, so if a member of CleverRaven says something like "I don't know much about armpit code, but maybe you want to do X", they're telling you not to take their word too seriously.
This can happen for a few reasons. If you're not sure which applies to you, feel free to ask for clarification.
An issue we run into occasionally is that our responses can be short and straightforward, which can rub people the wrong way. The intent is to be matter-of-fact and completely clear, not unkind. We have found that if we try to be too gentle, we leave room for confusion: people continue working on a thing that will never be OK to add, and wind up wasting more of their effort, which is a really bad outcome and more unkind in the long run. Remember that, first, text doesn't convey tone well; and second, we don't want to make it seem open to debate if it isn't. However, we guarantee that nobody wants you to feel badly for having ideas and excitement about the game.7
This is a thing that happens sometimes; because it's a rare and significant event, it often gets a bit of publicity and seems like something that happens more. At time of writing there have been roughly 1-2 reversions per month in the last year, which is around 0.2% of the PRs merged. Most of these are reverted for infrastructure reasons, and added back as soon as possible. It's very important to understand that on our end, we consider reversions a failure of the dev team to adequately review submissions. They mean that we messed up and we're fixing it as best we can.
The best way to protect yourself from getting something reverted, or rejected before merge, is to (1) discuss your project, especially with developers, and make sure it's appropriate, (2) get someone to review your PR before it's merged), and (3) keep your changes to individually small PRs where they can be properly reviewed and studied before being added. However, remember that by far most PRs are not reverted nor rejected.
If you're feeling overwhelmed by the amount of work being piled on you, first, we recommend making sure the suggestions are coming from someone with some authority on the matter. When in doubt, these issues are easiest to sort out on Discord, where it's easier to tell who has some authority. On GitHub we're doing our best to make sure that project members get a user badge, like this:
A "member" badge means this person has permissions with CleverRaven and so has a better chance of being correct, but if they say they're not an authority in this area, that means you shouldn't overvalue them either. As a last resort, consider pinging kevingranade or I-am-Erk on GitHub to come in and clarify, although we'd very much prefer you to come ask in Discord. It can also help to check if the suggested changes are in line with any of the official guides and documentation.
If the requested changes are coming from a trusted source, and it's more than you feel you can handle, it's all right to say as much. We might not mean that we expect you to do whatever is being suggested. Other times, the thing you're trying to do is just not going to be as easy as it looked. In that case, we'd prefer you to do it if you can, but it's all right to decide that we're asking for too much. These problems can usually be avoided with a well-discussed GitHub/Discourse post or Discord conversation. If you're extremely averse to having this happen, try to be patient and persistent and make sure you've got the go-ahead from a developer before beginning, but we want to emphasize that most of the time, this doesn't happen. The bigger your contribution is, the more important it becomes to get clearance.
When something gets added to the project, as soon as the PR goes out into the world, the traditional sense of "ownership" is relinquished and it becomes a collaborative creation effort. The person putting in the most effort is a sort of director for that content, but a lot of the time they finish their plans and there's plenty of room for more work to go in. If you'd like to make drastic changes, you should first get an idea whether or not someone is actively working on the thing you plan to change. For most of the content in the game, this is not the case, and we'd love someone to step up.8 Probably the best place to find out about this is in the narrative-dev channel on Discord, since the main concern is making sure your new ideas won't conflict with the long term plans being worked on.
As a general rule, in fact, we would prefer it if new contributors would feel welcome to alter and improve on the existing NPCs in game before adding a bunch of new ones! We have too many unfinished NPCs and quest lines as it is. Don't let this stop you from adding a brand new NPC, but definitely don't feel held back by not knowing who "owns" an existing bit of the game.
We don't think so, but obviously we're biased. First, make sure you're looking at the developer discord and not the fan discord or the old one that was subjected to a Nazi takeover (seriously).
If you're on the developer discord to talk about development, it's very difficult to get banned or kicked out, and you'll always get warnings first9. If you're worried about getting in trouble for your memes or fun chat times, we suggest just going to the community discord, where the rules are much more lax. It's still fine to chat on the developer discord, but we intentionally run it mainly for very focused discussion of the game. It's also the place to go to see the devs talking like normal people instead of giving dry technical responses on GH.
If someone is telling you they got banned from "devcord" for nothing at all without warning, there's a story they aren't telling you. This just isn't a thing that happens. Our ban records are public.
There's a common misunderstanding about the role of non-contributor players, or even non-dev contributors, in affecting the project direction, which is that we don't care about player feedback. It's not entirely false, but it's definitely not true; it should not be a reason to decide not to contribute.10 However, the question of what we think of player feedback on the project side is actually complex and worth examining in detail.
The short answer is, yes, of course, but this doesn't mean what some people might think.
We believe that the reason this project has thrived for so long is that we follow a consistent vision for the game, while allowing side projects and flavour tweaks to be included in the game. It's fine if you just don't like what we like. There are a few ways to reconcile that: you could work on a mod in repo, either your own or someone else's. You could develop and share a third-party mod that we haven't got any control over at all. You could join a fork, and help them out. You could fork the project and demonstrate your own vision for it. However, if you've looked around and you like where we're going, we'd love to have you join us, or even just play and have fun with our game.
If you took that away from the above, we'll probably never see eye-to-eye. However, we do actually care what players say. Very often, constructive discussion with players results in our goals remaining the same, with new ideas on how to reach those goals. Sometimes, we will listen to many well-reasoned arguments, and still not change our minds. That is because 'listening' and 'caring about what you say' are not the same as 'doing what we're told'. We've learned over the years that for some, this is never going to be sufficient, and again, we encourage those people to find ways to see their own goals achieved rather than continuing to be upset at us for not changing our own.
This section isn't necessary to read, but contains (we hope) some useful fact-checking and some fun or interesting history.
CDDA is a fork of a game called Cataclysm, developed by Whales. Cataclysm was a grab-bag apocalypse roguelike set in a vague near-future setting. Dark Days Ahead was forked by a group of people (Kevin Granade, TheDarklingWolf, and GlyphGryph) to be a more gritty, realistic zombie apocalypse game made from the same general concept.
We firmly believe that the reason CDDA has persevered and improved steadily since 2013 is that it has a consistent project direction. We're also aware that many people claim the project direction changed at some point in the past. This interview from 2013 and this one from about the same time show that the original developer team had much the same goals as we currently lay out in the design doc. A lot of the misconception comes down to changes that were left to ride from the original Cataclysm before the DDA fork, and were changed around 2018-2020.
To clear up a few common rumours that circulate in certain channels:
This merits its own section because it's such a frequent by-line in various Cataclysm communities. Kevin is mostly hands-off, although he is quite present and involved in a lot of discussion, but for some reason he is attributed as the primary source of all changes in Cataclysm (usually unpopular ones). We know this is usually meant as a joke, but it obscures credit from our broad base of contributors. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, the only way to get it added is to ask nicely. At any given time there are around 50-100 different contributors of various levels working on the project, including both regulars and new faces. If something was changed, it's most likely one of these people changed it, and Kevin simply didn't say 'no'.
As a classic example, when we first added the mod inclusion criteria and set a bunch of mods to obsolete, Kevin had very little involvement in the process. It was a collaboration by around two dozen devs and contributors who were collectively tired of bugfixing mods none of us used. Years down the road, we continue to see this cited as an example of Kevin exerting authority on the project, when his main involvement was to agree it was our call to make as the ones doing most of the work.13 Similar situations have happened dozens of times.
Any prospective contributor should understand that we do not consider realism to be the goal of the design. Rather, we are aiming for verisimilitude. That is to say, most of the time, things should work the way you would expect them to work.14 Many things that would be more realistic may be nixed because of problems with play experience or play balance. You can find a lot more detail about this in the design document.
In general, the most common citation of "realism" online comes when glitches in experimental are mistaken for intended design. An example was when charges were being removed as a part of a major code infrastructure change with no intended player impact at all. This caused several months of glitches, like players having to move salt in individual pinches. This was frequently called a "realism change", not a bug, in certain circles. While funny, this attitude can be actively harmful to the project, deterring people from fixing bugs because they get the impression it's intended play. If someone has said that a seemingly hostile and illogical game mechanic is the way it is due to "realism", they're probably wrong, either because the mechanic is bugged or because QoL improvements are desired to make it less frustrating.
Short answer: Because someone chose to work on X, not Y.
Longer answer: Sometimes, the more important system is much harder or more intimidating (eg NPC AI). Most of the time, though, it's just that we have infinite things to work on and we have to pick something. If a particular system is important and interesting to you, the only way to ensure someone works on it is to work on it yourself. Chances are this is not as difficult as it sounds. If you just can't do that, sometimes you can get headway by becoming a cheerleader for it. Learn what needs to be done, and make it sound appealing to people who might know how to do it. Generally, this isn't going to work well unless you also contribute your own stuff, but for example a dedicated tileset artist or translator might have a lot of sway in convincing a coder to do them a favour.
For example, why did science equipment get added but you could only loot it in one location?
Usually, the person implementing it didn't want their PR to explode into a whole bunch of extra features (this doc even has a FAQ entry on that problem). This is a consequence of the game being experimental, not the intended design, and the intended fix is that someone should just add missing feature Z: eg, add science equipment to more spawn lists. It's not the result of malice, it's the side effect of wanting to do something right, but not having the resources to be in every place at every time.
Did you actually read all that, or just scroll down? Massive kudos if you read it.
In the end, we hope you'll share our passion for this project and decide to come join us in contributing to it, and we hope that you find this document helpful in clearing up various odd misconceptions about how development works that have gathered over all the years of project management.
Footnotes
Kevin is also much more likely to have strong opinions about code maintainability and architecture than he is about lore stuff, as a general rule. ↩
At least by certain definitions of fun, which may or may not involve being eaten by a mi-go. ↩
There's a tendency for theory crafting to be louder than playtests, and we've had severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. ↩
A good example of this is that we tried to sort out bow balance for many years back and forth until finally adding weak points, because ultimately the issue was that arrows shouldn't be able to get through a lot of things bullets can, but almost all armours and defenses have gaps an archer can target. ↩
This happened to I-am-Erk somehow and he's still not sure why he hasn't run away screaming. ↩
Discourse is a less active forum, but that can actually make it a better place to make a proposal. Many of the devs still regularly check it, and you're much less likely to get missed in the background noise. You just might have to be a little more patient as we're not checking it every day. ↩
Unless your ideas are dumb, then…… but jokes aside, even a lot of the ideas we have to reject are good ideas, they're just either not practical for our project or they take it in directions we'd rather avoid. We might be blunt about saying no, but we do seriously respect the creativity. ↩
At time of writing, the main faction to check in on is Hub01, which is being very actively developed by Candlebury with long term plans. The Exodii are a distant second: there are a lot of plans here, but I-am-Erk is open about not having the time needed to actively develop them and would be very open to new directions if it meant getting them more actively handled. This is as of May 2024 and subject to change. ↩
Unless you're a spambot, but then how are you reading this? ↩
Also, if you want to listen to player feedback on your additions to the game, you're welcome to do it however you like! ↩
In fact, in some ways, the more popular DDA gets the more trouble it causes from a project management standpoint: we get more drama and have to handle more top-heavy admin work than we would with a smaller project. "Growing our audience" is something that has happened organically, and we love new people trying out the game, but at the same time it's definitely not a goal. ↩
The general design is quite flexible. For example when Venera3 started contributing, we were considering removing giant insects from the lore entirely. Now we all have to deal with those infuriating giant wasps and it's all his fault. ↩
At time of writing this is still the most disliked PR in the entire project, and it's kind of interesting to note how little Kevin had to do with it. ↩
To make matters worse, there are a lot of ways we expect things to work that turn out to not be really as clear as they seem, either due to popular "movie logic" misunderstandings, or because reality is rarely simple. Hunger is a fun example of this. ↩