From 54637e9483ae6703a019d3560171da53eb492052 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 13:49:45 -0700 Subject: [PATCH 01/37] Create development_process.md --- doc/development_process.md | 127 +++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 doc/development_process.md diff --git a/doc/development_process.md b/doc/development_process.md new file mode 100644 index 0000000000000..9cdb2c6d66d83 --- /dev/null +++ b/doc/development_process.md @@ -0,0 +1,127 @@ +# The DDA Development Process + +**A guide for new and prospective contributors, or just for people curious about how the devs understand things.** + +This guide is intended to describe how the Cataclysm: Dark Days Ahead project is organized, 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, as individuals are welcome to disagree with the team stance. + +This document assumes you have a basic understanding how GitHub works. Please see the [guide for new contributors](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html), which talks about some of the common ideas we hear for the project and offers reasons about why they might not have been added yet. [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. + +## The basic concept + +At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the Cleverraven group that runs this branch of the code. We (as in, all the members of the development team) often have different ideas of what's fun or good, and we put those things in our own mods (eg Aftershock, Magiclysm, and Dark Days of the Dead) if we can't work them into the main game. 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. He tends to have stronger opinions about the infrastructure of the project, as one might expect from a software engineer working for more than a decade on a single massive open-source project. + +## Helpful tips for prospective contributors + +This section is going to be super long, and you're welcome to read it all if you like, but here's the most important TL;DR points: + +1. It's quite rare for a simple, reasonable contribution to be rejected or reverted. For larger projects, you might want to get more experience with the project or clear it with a developer first. +2. If it sounds like your small job is being turned into a big unmanageable job, check if the ideas being thrown around are things *you* have to do, or just people getting excited. Usually it's just excitement, it means you have a cool idea but not that you need to do a bunch more stuff. +3. If you're getting negative feedback or being told you have to do something a certain way, make sure it's someone with authority before you start feeling discouraged. +4. Please don't take it personally if a developer gives you a short, gruff answer. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact. + +### What if my contributions aren't accepted? + +If what you're doing is simple, like fixing typos, 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 higher up in the project. There are two good ways to do that: either create an Issue post on GitHub, or chat in [the developer discord](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel 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 to the project. + +By and large, 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 basically skip this entire document. You'll be fine. It's already a small minority of things that turn out to not work out and need to be re-thought, and if you're easygoing about that risk then you have nothing to worry about. If that possibility concerns you though, reading on may help you to figure out how to limit the risk of creating something only to find it won't get in, or needs a lot more work than you thought. + +If you've created an Issue 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. + +#### What if different people have different opinions of my idea? + +The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are the best ones to listen to, such as I-am-Erk, KorgGent, esotericist, Venera3, Candlebury, Renech, and more. After that, people with blue or magenta names on discord (the collaborators and moderators) often have a very good idea, and you should listen carefully to their feedback. 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 that indicates a person is a member of Cleverraven with at least a little authority. + +#### My idea was rejected, changed beyond recognition, or requires a lot more than I expected. + +This can happen for a few reasons. If you're not sure which applies to you, feel free to ask for clarification. + +* Sometimes, your idea sparks a huge conversation, and the next thing you know it seems like you're on the hook to overhaul armpit f +mechanics before you can start. *Please, feel free to mention if you feel this way*. This usually means you've hit something cool that we're all excited about. It often doesn't mean we expect you to add whatever we've started riffing on, and you're fine to just put in whatever small thing you originally wanted. We're all just huge nerds, and we know that sometimes we get carried away. +* Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws. Often it's better not to add a simplified version that will cause us problems down the road, because we then need to either revert or rework that solution to go on. If you're not able to do the harder work, you'll have to find a different idea. We won't think less of you for that. +* Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. Remember that almost all the senior devs have our own pet mods; sometimes, things just go better there, and that's okay. + +An issue we run into occasionally is that our responses to ideas we've heard a lot of times before can be short, and this leaves room for misinterpretation. The intent is to be matter-of-fact and completely clear. 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. Remember that, first, text doesn't convey tone well; second, we've often had this conversation twenty times already and don't want to make it seem open to debate; and third, we're all the sort of people who choose to program a complex niche game *as a hobby*. We're not all the most, um, socially skilled people. However, we can guarantee that nobody wants you to feel badly for having ideas and excitement about the game. We just cannot always be there to meet you equally. + +#### I've heard a lot of things get merged to the project, then reverted. + +This is a thing that happens sometimes. 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. For example, a PR might be reverted because the code has unforseen consequences that create bugs that will be very hard to fix; or, it might have attribution errors. It's very important to understand that on our end, **we consider reversions a failure of the dev team**. They aren't your fault as a contributor: if something is getting reverted it's because we failed to properly review it. They don't mean that your contributions aren't valued. They mean that we messed up and we're fixing it as best we can. The fact that it got merged in the first place often means that it's appropriate to the game, but we strongly advise not working on it further until you've confirmed that. + +The best way to protect yourself from getting something reverted, or rejected before merge, is to (1) discuss your project on github or discord with developers and make sure it's appropriate, (2) [get someone to review your PR before it's merged](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md), 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. + +#### I've started a PR and now I'm getting a ton of requested changes. + +Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with cleverraven. On GitHub, this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: +![image](https://gist.github.com/assets/45136638/a0131586-a61f-4186-bd1f-01e8228cfd1c) + +A "member" badge means this person has permissions with cleverraven and so has a pretty high chance of being correct. A "contributor" badge means they've worked with the project before, but don't have any official authority. Unfortunately, GitHub makes these badges very hard to assign to members of the project. As a last resort, consider pinging kevingranade or i_am_erk on github to clarify, although we'd very much prefer you to come ask in discord. + +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. Just as mentioned above, **this may be the result of enthusiasm** and we might be able to meet you halfway, or we might not even mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or discord conversation, but there's no way to completely guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. It's a very small minority of PRs that become complex issues needing a lot of management and discussion like this, chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. + +#### You keep suggesting the discord, but I've heard it's really strict. + +We don't think so, but obviously we're biased. First, make sure you're looking at [the developer discord](https://discord.gg/hqWgHC8TKY) 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. If you're worried about getting in trouble for your memes or fun chat times, we suggest just going to [the community discord](https://discord.gg/byxwnAU +), 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 not the place to go for memes about cargo socks. It *is* 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. + +### I've heard that you don't care about player feedback at all. + +This is a common concern we hear that occasionally leads people to decide not to contribute. It's not entirely false, and it's definitely not true; it should not be a reason to decide not to contribute. First, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it as much as you like! However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. + +#### Do we care about the players? + +The short answer is, *yes, of course*, but this doesn't mean what some people might think. + +1. We are not selling a product, so we don't care about mass appeal. 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*. +2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that you, the devs, like into something I prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think this mass appeal is anywhere near as obvious as it can seem from inside a drama thread. +3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a goal we have. When it's possible to do it without extra work, we're happy to keep things set as options that can be adjusted with mods, especially since most of the devs also have our own mods. However, including player-facing adjustments for every conceivable game setting is not something we want to maintain. We could write four paragraphs explaining why not, but in the end, it comes down to number 2 plus a bunch of details on managing the code. +4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. We try to keep the experimental branch of the game playable, of course, but it's not intended to represent the curated CDDA experience: experimental is often rendered very weird and imbalanced, sometimes for months at a time, as we *experiment* with things. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option when requested. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. In years of working on the project, we've seen it happen dozens upon dozens of times, and play out the same way every time. This is one of many things that can make player feedback difficult to properly assess. +5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. This is Kevin's fork of the project. If you made your own fork, you could allow people to vote on design decisions and see how it came out, but this is the fork Kevin runs and he doesn't want to do that, he wants to make his own game. The devs generally think this makes for a better game, but who knows, maybe we're wrong. However, the project also isn't a dictatorship. It's more like an open forum with a moderator. If you have opinions about something, make your case for it. Lots of things have been added to the project that wouldn't have made it in if someone weren't passionate about them. The general design is quite flexible, and 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. If what you want isn't *incompatible* with the game concept, and you make a good case for it, you can very often change our minds. + +We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. It's fine if you don't agree with what we want. There are a few ways to reconcile that: you could work on a mod in mainline, 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 like Bright Nights, and help them out. You could fork the project and demonstrate your own vision for it. *We genuinely support all these options*, and this seems to confuse some people. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. However, if you've looked around and you like where we're going, we'd love to have you join us. + +##### So wait, it sounds like you're just going to do whatever you want and you don't care what the players say. + +If you took that away from the above, and a few people definitely did, we'll probably never see eye-to-eye. However, we do actually care what players say. We all love talking to the players. Seriously, we do, that's why we do so much of it. Players, even players who never have and never will contribute directly to the game, have *wildly* altered the course of DDA's development in countless ways. It's just that this has not, and never will, manifest in Kevin deciding to shift design goals because a bunch of people angrily demanded it. Very often, constructive discussion with players manifests in our overall *goals* remaining the same, but us reaching a new agreement in *how to reach those goals*. Sometimes, of course, we will listen to many well-reasoned arguments from intelligent and passionate people, and still not change our minds. That is, of course, because 'listening' and 'caring about what you say' is not the same as 'doing what we're told to do'. We've learned over the years that for some, this is not 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. + +## Supplemental Material + +This section isn't necessary to read, but contains (we hope) some useful fact-checking and some fun or interesting history. + +### A Very Brief History of DDA + +CDDA is a fork of a game called Cataclysm, developed by a guy called 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) who wanted a more gritty, realistic zombie apocalypse game made from the same general concept. Why they picked Cataclysm is anyone's guess (Kevin could probably guess, but he's not writing this document). + +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](https://web.archive.org/web/20140211144953/http://www.jacehallshow.com/news/gaming/preview/20130626/ascii-goodness-living-breathing-3d-world-cataclysm-dark-days/) and [this one from about the same time](http://www.roguelikeradio.com/2013/07/episode-75-cataclysm-dark-days-ahead.html?m=1) show that the original developer team had much the same goals as we currently have 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 removed in a dedicated push around 2018-2020. + +To clear up a few common rumours that circulate in certain channels: +- Kevin did not steal the project from anyone. The other original devs just left, for various reasons. It's a hobby project, people come and go. There was no falling out or hard feelings. +- Over the years we've lost a lot of developers. The reason is not as dramatic as you might think: by and large, people get bored and move on to other places. The number of major fallings-out can be counted on one hand, in over a decade of development. +- We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. Community drama followed shortly afterwards, but not for related reasons. +- That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and reddit shut down 3rd party apps. Nothing particularly exciting. + +#### Why did Kevin do this to me? + +This merits its own section because it's such a frequent by-line in various Cataclysm communities. For the most part, for the last five or six years, Kevin has been fairly hands-off in the direct development of CDDA. He is quite present and involved in a lot of design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is a meme, but it's actually one that we consider harmful, since it obscures credit from our extremely broad base of contributors. As mentioned earlier in this document, Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides to ask nicely. If a feature was added to the game, chances are actually pretty high that someone else did it. 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, statistically it's most likely one of these people, not Kevin, changed it, and Kevin simply didn't say 'no'. + +### Realism as a design goal + +This is a much repeated buzz word. 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. This is a subtle but very important difference. Many things that would be more realistic may be nixed because of problems with play experience or play balance; for example, at time of writing, we've repeatedly shot down efforts that would make regular laundry and hygeine important, because while realistic these would be tedious and frustrating unless implemented in extremely specific ways. You can find a lot more detail about this in [the design document](https://docs.cataclysmdda.org/Lore/design-balance.html). + +In general, the most common citation of "realism" online comes from laughable misunderstandings where glitches in experimental are mistaken for intended design in certain communities. 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 shakedown with glitches like players having to move salt in individual pinches, an obviously unintended consequence that was remedied pretty quickly. This was frequently claimed to be a "realism change", not a bug, in certain circles. While funny to think back on, this attitude has at times been actively harmful to the project, with people feeling discouraged from fixing bugs because they get the impression it's intended play. Almost universally, 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. + +### Why did X system get worked on while the more important Y system didn't? + +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 possible 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 learn how to code and to work on it yourself. Chances are this is not as difficult as it sounds. However, if you just can't do that for some reason, 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 might have a lot of sway in convincing a coder to do them a favour. + +## The Bottom Line + +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. From 24e532ac39e54424d97ef74a23462dcf4eac1d5f Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 13:56:53 -0700 Subject: [PATCH 02/37] Update development_process.md --- doc/development_process.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/development_process.md b/doc/development_process.md index 9cdb2c6d66d83..68bd8479eb83d 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -103,6 +103,7 @@ To clear up a few common rumours that circulate in certain channels: - Over the years we've lost a lot of developers. The reason is not as dramatic as you might think: by and large, people get bored and move on to other places. The number of major fallings-out can be counted on one hand, in over a decade of development. - We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. Community drama followed shortly afterwards, but not for related reasons. - That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and reddit shut down 3rd party apps. Nothing particularly exciting. +- We don't have any animosity to the other major forks of the game. Mostly, we are glad they exist, even though we know how some of them talk about us. It's our opinion that it's a *good thing* if someone doesn't like our way of managing the project and so has a different place to go instead of feeling bitter about how we run our hobby project. #### Why did Kevin do this to me? From 9ca522b913c97f1e19c9b6729050265d5a70f5f2 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:20:28 -0700 Subject: [PATCH 03/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 68bd8479eb83d..672a19acc5783 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -80,7 +80,7 @@ The short answer is, *yes, of course*, but this doesn't mean what some people mi 2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that you, the devs, like into something I prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think this mass appeal is anywhere near as obvious as it can seem from inside a drama thread. 3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a goal we have. When it's possible to do it without extra work, we're happy to keep things set as options that can be adjusted with mods, especially since most of the devs also have our own mods. However, including player-facing adjustments for every conceivable game setting is not something we want to maintain. We could write four paragraphs explaining why not, but in the end, it comes down to number 2 plus a bunch of details on managing the code. 4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. We try to keep the experimental branch of the game playable, of course, but it's not intended to represent the curated CDDA experience: experimental is often rendered very weird and imbalanced, sometimes for months at a time, as we *experiment* with things. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option when requested. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. In years of working on the project, we've seen it happen dozens upon dozens of times, and play out the same way every time. This is one of many things that can make player feedback difficult to properly assess. -5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. This is Kevin's fork of the project. If you made your own fork, you could allow people to vote on design decisions and see how it came out, but this is the fork Kevin runs and he doesn't want to do that, he wants to make his own game. The devs generally think this makes for a better game, but who knows, maybe we're wrong. However, the project also isn't a dictatorship. It's more like an open forum with a moderator. If you have opinions about something, make your case for it. Lots of things have been added to the project that wouldn't have made it in if someone weren't passionate about them. The general design is quite flexible, and 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. If what you want isn't *incompatible* with the game concept, and you make a good case for it, you can very often change our minds. +5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it. The general design is quite flexible, and 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. If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. It's fine if you don't agree with what we want. There are a few ways to reconcile that: you could work on a mod in mainline, 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 like Bright Nights, and help them out. You could fork the project and demonstrate your own vision for it. *We genuinely support all these options*, and this seems to confuse some people. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. However, if you've looked around and you like where we're going, we'd love to have you join us. From 8aa707971acb71ec4108d9f65278a1da3fe07709 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:26:47 -0700 Subject: [PATCH 04/37] Update development_process.md --- doc/development_process.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 672a19acc5783..3dcb6ef7a3507 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -68,9 +68,9 @@ If you're on the developer discord to talk about development, it's very difficul 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. -### I've heard that you don't care about player feedback at all. +### How does player feedback affect the project's development? -This is a common concern we hear that occasionally leads people to decide not to contribute. It's not entirely false, and it's definitely not true; it should not be a reason to decide not to contribute. First, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it as much as you like! However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. +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, and it's definitely not true; it should not be a reason to decide not to contribute. First, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it as much as you like! However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. #### Do we care about the players? @@ -82,7 +82,7 @@ The short answer is, *yes, of course*, but this doesn't mean what some people mi 4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. We try to keep the experimental branch of the game playable, of course, but it's not intended to represent the curated CDDA experience: experimental is often rendered very weird and imbalanced, sometimes for months at a time, as we *experiment* with things. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option when requested. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. In years of working on the project, we've seen it happen dozens upon dozens of times, and play out the same way every time. This is one of many things that can make player feedback difficult to properly assess. 5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it. The general design is quite flexible, and 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. If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. -We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. It's fine if you don't agree with what we want. There are a few ways to reconcile that: you could work on a mod in mainline, 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 like Bright Nights, and help them out. You could fork the project and demonstrate your own vision for it. *We genuinely support all these options*, and this seems to confuse some people. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. However, if you've looked around and you like where we're going, we'd love to have you join us. +We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. It's fine if you don't agree with what we want. There are a few ways to reconcile that: you could work on a mod in mainline, 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 like Bright Nights, and help them out. You could fork the project and demonstrate your own vision for it. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. 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. ##### So wait, it sounds like you're just going to do whatever you want and you don't care what the players say. @@ -103,7 +103,7 @@ To clear up a few common rumours that circulate in certain channels: - Over the years we've lost a lot of developers. The reason is not as dramatic as you might think: by and large, people get bored and move on to other places. The number of major fallings-out can be counted on one hand, in over a decade of development. - We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. Community drama followed shortly afterwards, but not for related reasons. - That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and reddit shut down 3rd party apps. Nothing particularly exciting. -- We don't have any animosity to the other major forks of the game. Mostly, we are glad they exist, even though we know how some of them talk about us. It's our opinion that it's a *good thing* if someone doesn't like our way of managing the project and so has a different place to go instead of feeling bitter about how we run our hobby project. +- We don't have any animosity to the other major forks of the game. Mostly, we are glad they exist, even though we know how some of them talk about us. It's our opinion that it's a *good thing* if someone who doesn't like our way of managing the project has a different place to go. We don't want to be dictators of our tiny corner of the internet, we want to make a neat game with as little drama as possible. #### Why did Kevin do this to me? From ed5a426a57fa9293ebce953ed45c1d58b1709f09 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:28:07 -0700 Subject: [PATCH 05/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 3dcb6ef7a3507..fcd2cb583394f 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -1,6 +1,6 @@ # The DDA Development Process -**A guide for new and prospective contributors, or just for people curious about how the devs understand things.** +**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 organized, 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, as individuals are welcome to disagree with the team stance. From 21bad40c9d8717dc0a2776f8720b8c69eadd4ecf Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:28:51 -0700 Subject: [PATCH 06/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index fcd2cb583394f..161cac005a781 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -17,7 +17,7 @@ This section is going to be super long, and you're welcome to read it all if you 1. It's quite rare for a simple, reasonable contribution to be rejected or reverted. For larger projects, you might want to get more experience with the project or clear it with a developer first. 2. If it sounds like your small job is being turned into a big unmanageable job, check if the ideas being thrown around are things *you* have to do, or just people getting excited. Usually it's just excitement, it means you have a cool idea but not that you need to do a bunch more stuff. 3. If you're getting negative feedback or being told you have to do something a certain way, make sure it's someone with authority before you start feeling discouraged. -4. Please don't take it personally if a developer gives you a short, gruff answer. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact. +4. Please don't take it personally if a developer gives you a short, gruff answer. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact, not to be unkind. ### What if my contributions aren't accepted? From 557d1d55cb57dd1cdf33f8fe3b6c669d9b224b9b Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:45:14 -0700 Subject: [PATCH 07/37] Update development_process.md --- doc/development_process.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 161cac005a781..66e1b4a2be468 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -31,7 +31,10 @@ If you've created an Issue and aren't getting much feedback, try reaching out on The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are the best ones to listen to, such as I-am-Erk, KorgGent, esotericist, Venera3, Candlebury, Renech, and more. After that, people with blue or magenta names on discord (the collaborators and moderators) often have a very good idea, and you should listen carefully to their feedback. 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 that indicates a person is a member of Cleverraven with at least a little authority. +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 that indicates a person is a member of Cleverraven with at least a little authority, like this: +![image](https://gist.github.com/assets/45136638/a0131586-a61f-4186-bd1f-01e8228cfd1c) + +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 trying to tell you not to take their word too seriously. #### My idea was rejected, changed beyond recognition, or requires a lot more than I expected. @@ -42,20 +45,20 @@ mechanics before you can start. *Please, feel free to mention if you feel this * Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws. Often it's better not to add a simplified version that will cause us problems down the road, because we then need to either revert or rework that solution to go on. If you're not able to do the harder work, you'll have to find a different idea. We won't think less of you for that. * Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. Remember that almost all the senior devs have our own pet mods; sometimes, things just go better there, and that's okay. -An issue we run into occasionally is that our responses to ideas we've heard a lot of times before can be short, and this leaves room for misinterpretation. The intent is to be matter-of-fact and completely clear. 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. Remember that, first, text doesn't convey tone well; second, we've often had this conversation twenty times already and don't want to make it seem open to debate; and third, we're all the sort of people who choose to program a complex niche game *as a hobby*. We're not all the most, um, socially skilled people. However, we can guarantee that nobody wants you to feel badly for having ideas and excitement about the game. We just cannot always be there to meet you equally. +An issue we run into occasionally is that our responses to ideas we've heard a lot of times before can be short and blunt, which can rub people the wrong way. The intent is to be matter-of-fact and completely clear. 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. Remember that, first, text doesn't convey tone well; second, we've often had this conversation twenty times already and don't want to make it seem open to debate; and third, we're all the sort of people who choose to program a complex niche game *as a hobby*. We're not all the most, um, socially skilled people. However, we can guarantee that nobody wants you to feel badly for having ideas and excitement about the game. We just cannot always be there to meet you equally. #### I've heard a lot of things get merged to the project, then reverted. -This is a thing that happens sometimes. 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. For example, a PR might be reverted because the code has unforseen consequences that create bugs that will be very hard to fix; or, it might have attribution errors. It's very important to understand that on our end, **we consider reversions a failure of the dev team**. They aren't your fault as a contributor: if something is getting reverted it's because we failed to properly review it. They don't mean that your contributions aren't valued. They mean that we messed up and we're fixing it as best we can. The fact that it got merged in the first place often means that it's appropriate to the game, but we strongly advise not working on it further until you've confirmed that. +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 a lot. 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. For example, a PR might be reverted because the code has unforseen consequences that create bugs that will be very hard to fix; or, it might have attribution errors. It's very important to understand that on our end, **we consider reversions a failure of the dev team**. They aren't your fault as a contributor: if something is getting reverted it's because we failed to properly review it. They don't mean that your contributions aren't valued. They mean that we messed up and we're fixing it as best we can. The fact that it got merged in the first place often means that it's appropriate to the game, but we strongly advise not working on it further until you've confirmed that. The best way to protect yourself from getting something reverted, or rejected before merge, is to (1) discuss your project on github or discord with developers and make sure it's appropriate, (2) [get someone to review your PR before it's merged](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md), 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. #### I've started a PR and now I'm getting a ton of requested changes. -Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with cleverraven. On GitHub, this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: +Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with cleverraven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: ![image](https://gist.github.com/assets/45136638/a0131586-a61f-4186-bd1f-01e8228cfd1c) -A "member" badge means this person has permissions with cleverraven and so has a pretty high chance of being correct. A "contributor" badge means they've worked with the project before, but don't have any official authority. Unfortunately, GitHub makes these badges very hard to assign to members of the project. As a last resort, consider pinging kevingranade or i_am_erk on github to clarify, although we'd very much prefer you to come ask in discord. +A "member" badge means this person has permissions with cleverraven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. 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. Just as mentioned above, **this may be the result of enthusiasm** and we might be able to meet you halfway, or we might not even mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or discord conversation, but there's no way to completely guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. It's a very small minority of PRs that become complex issues needing a lot of management and discussion like this, chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. From 8f3c1b4bb22c33b41bf0c46c01bf26cf4169b8db Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:47:10 -0700 Subject: [PATCH 08/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 66e1b4a2be468..6b9d41f160f91 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -14,7 +14,7 @@ At its core, CDDA is a survival simulation game. [The design doc outlines what This section is going to be super long, and you're welcome to read it all if you like, but here's the most important TL;DR points: -1. It's quite rare for a simple, reasonable contribution to be rejected or reverted. For larger projects, you might want to get more experience with the project or clear it with a developer first. +1. Most simple, reasonable contributions get accepted. For larger projects, you might want to get more experience with the project or clear it with a developer first. 2. If it sounds like your small job is being turned into a big unmanageable job, check if the ideas being thrown around are things *you* have to do, or just people getting excited. Usually it's just excitement, it means you have a cool idea but not that you need to do a bunch more stuff. 3. If you're getting negative feedback or being told you have to do something a certain way, make sure it's someone with authority before you start feeling discouraged. 4. Please don't take it personally if a developer gives you a short, gruff answer. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact, not to be unkind. From 7dbd9e0d653fa4ead7110a29b8e86ba7e4e963a2 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:49:12 -0700 Subject: [PATCH 09/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 6b9d41f160f91..0e8cc7f60ce0e 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -51,7 +51,7 @@ An issue we run into occasionally is that our responses to ideas we've heard a l 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 a lot. 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. For example, a PR might be reverted because the code has unforseen consequences that create bugs that will be very hard to fix; or, it might have attribution errors. It's very important to understand that on our end, **we consider reversions a failure of the dev team**. They aren't your fault as a contributor: if something is getting reverted it's because we failed to properly review it. They don't mean that your contributions aren't valued. They mean that we messed up and we're fixing it as best we can. The fact that it got merged in the first place often means that it's appropriate to the game, but we strongly advise not working on it further until you've confirmed that. -The best way to protect yourself from getting something reverted, or rejected before merge, is to (1) discuss your project on github or discord with developers and make sure it's appropriate, (2) [get someone to review your PR before it's merged](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md), 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. +The best way to protect yourself from getting something reverted, or rejected before merge, is to (1) discuss your project on github or discord with developers and make sure it's appropriate, (2) [get someone to review your PR before it's merged]([https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md](https://docs.cataclysmdda.org/reviewing_PR_guide.html)), 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. #### I've started a PR and now I'm getting a ton of requested changes. From 06581a92a9f8fdb04c5ff34243ae8b6228e16ada Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:49:31 -0700 Subject: [PATCH 10/37] Update reviewing_PR_guide.md --- doc/reviewing_PR_guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/reviewing_PR_guide.md b/doc/reviewing_PR_guide.md index 4a2aff7d5514b..3b753e5a70425 100644 --- a/doc/reviewing_PR_guide.md +++ b/doc/reviewing_PR_guide.md @@ -1,4 +1,6 @@ -# Background & Introduction +# Guide to Reviewing PRs + +## Background & Introduction As the CDDA project grows, it is becoming harder for the few volunteers in project management to keep constant tabs on what gets merged. Over the years, we've found there are two possible ways this shakes out. Whenever the lead devs are away for real-life reasons for a while, either we get a huge backlog of PRs, or we wind up with a few things getting merged that really shouldn't have been. This leads to having to revert work by enthusiastic and well-meaning contributors, which we consider a very bad outcome. This document aims to do two things to reduce this: From 4bead676189daa0dbb36e6ac3f72735b68a63be3 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 14:50:34 -0700 Subject: [PATCH 11/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 0e8cc7f60ce0e..5be8391dc7152 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -2,7 +2,7 @@ **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 organized, 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, as individuals are welcome to disagree with the team stance. +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, as individuals are welcome to disagree with the team stance. This document assumes you have a basic understanding how GitHub works. Please see the [guide for new contributors](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html), which talks about some of the common ideas we hear for the project and offers reasons about why they might not have been added yet. [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. From 5ba7a5561fa743cb9ba072737e9a1c9e5a35cf18 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 15:51:29 -0700 Subject: [PATCH 12/37] Update development_process.md --- doc/development_process.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/doc/development_process.md b/doc/development_process.md index 5be8391dc7152..84319a4102c41 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -10,6 +10,43 @@ This document assumes you have a basic understanding how GitHub works. Please s At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the Cleverraven group that runs this branch of the code. We (as in, all the members of the development team) often have different ideas of what's fun or good, and we put those things in our own mods (eg Aftershock, Magiclysm, and Dark Days of the Dead) if we can't work them into the main game. 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. He tends to have stronger opinions about the infrastructure of the project, as one might expect from a software engineer working for more than a decade on a single massive open-source project. +## The structure of the project itself + +### Experimental/Stable + +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 would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try hard to make sure major features in stable are playable and not a detriment to the enjoyment of the game. We try to keep stable balanced and fun. + +On the other hand, in the experimental branch, we allow things to get broken. We don't want things to be broken long-term, and we rarely actively try to break them, but we don't fret it if they do. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For this reason, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. +- First, we assess if the playtest feedback is valid. This is usually the hardest part, and it becomes harder when a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to outweigh playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. +- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. The most common way to find a solution is to think about how the mechanic in question should work in real life: for example, bow balance - a bugbear of design that plagued us for years - was finally solved by developing weak points in monster armour that could be hit with arrows. +- If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix. This is also where the experimental/stable thing becomes relevant. For example, we will often leave a feature in experimental that makes the game unpleasant, because we do want that feature, and we want it working as intended. On a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. + +### Mainline, in-repo mods, third party mods, and forks + +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; you just probably don't treat it as one. This version, which we often call 'mainline' here, is the one we curate and treat the way we want to treat, usually with about 50-100 contributors from all over the internet helping out at any given time. + +**In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include in mainline. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to the developers of the game who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. If you leave and stop maintaining it, we may allow someone else to take it over when it breaks, or we might hide and eventually remove it. If you came back and wanted to revive it, we'd probably let you. + +**Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. To our knowledge there's no central repository of third party mods, which seems like a bit of a shame. + +**Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. From our perspective, there's no rivalry here. We're very happy BN exists and we want them to thrive. Sometimes they use our source code and vice versa, due to the open nature of the license. + +### Project roles + +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, with only a few exceptions, because as a volunteer project we mostly treat this as an open forum for discussion, not a project with a strict chain of command. Unfortunately, this can be a bit confusing. + +* **Cleverraven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of Cleverraven and whether or not they have any official stance in what cleverraven does. Not all Cleverraven members are lead developers with merge permissions. However, anyone who is a member of Cleverraven has at least *some* official trust and experience with the project. +* The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. +* **Lead developers** have merge permissions with Cleverraven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "lead" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. +* **Developers** are members of Cleverraven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. +* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for Cleverraven, necessarily, but most of the time they know what they're talking about. +* **The dev team** is a super vague term that means, roughly, "the developers and sometimes the collaborators too". +* **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. +* **Core contributors** is another super vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". +* **Players** are the people whose lives we try to ruin, who somehow keep coming back for more. What is their deal? We may never know. + ## Helpful tips for prospective contributors This section is going to be super long, and you're welcome to read it all if you like, but here's the most important TL;DR points: From 2ce8f8ee296f2c11aa7f1de9c4903ccc5d0818d5 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 15:51:54 -0700 Subject: [PATCH 13/37] Update development_process.md --- doc/development_process.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 84319a4102c41..bbb95d21d11a0 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -27,11 +27,9 @@ On the other hand, in the experimental branch, we allow things to get broken. W 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; you just probably don't treat it as one. This version, which we often call 'mainline' here, is the one we curate and treat the way we want to treat, usually with about 50-100 contributors from all over the internet helping out at any given time. -**In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include in mainline. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to the developers of the game who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. If you leave and stop maintaining it, we may allow someone else to take it over when it breaks, or we might hide and eventually remove it. If you came back and wanted to revive it, we'd probably let you. - -**Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. To our knowledge there's no central repository of third party mods, which seems like a bit of a shame. - -**Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. From our perspective, there's no rivalry here. We're very happy BN exists and we want them to thrive. Sometimes they use our source code and vice versa, due to the open nature of the license. +* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include in mainline. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to the developers of the game who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. If you leave and stop maintaining it, we may allow someone else to take it over when it breaks, or we might hide and eventually remove it. If you came back and wanted to revive it, we'd probably let you. +* **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. To our knowledge there's no central repository of third party mods, which seems like a bit of a shame. +* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. From our perspective, there's no rivalry here. We're very happy BN exists and we want them to thrive. Sometimes they use our source code and vice versa, due to the open nature of the license. ### Project roles From e1befd8729951e1a75e430422eca29e9101074a2 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 15:53:10 -0700 Subject: [PATCH 14/37] Update development_process.md --- doc/development_process.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index bbb95d21d11a0..f5c85ab6f463d 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -67,8 +67,7 @@ If you've created an Issue and aren't getting much feedback, try reaching out on The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are the best ones to listen to, such as I-am-Erk, KorgGent, esotericist, Venera3, Candlebury, Renech, and more. After that, people with blue or magenta names on discord (the collaborators and moderators) often have a very good idea, and you should listen carefully to their feedback. 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 that indicates a person is a member of Cleverraven with at least a little authority, like this: -![image](https://gist.github.com/assets/45136638/a0131586-a61f-4186-bd1f-01e8228cfd1c) - +![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) 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 trying to tell you not to take their word too seriously. #### My idea was rejected, changed beyond recognition, or requires a lot more than I expected. @@ -91,7 +90,7 @@ The best way to protect yourself from getting something reverted, or rejected be #### I've started a PR and now I'm getting a ton of requested changes. Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with cleverraven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: -![image](https://gist.github.com/assets/45136638/a0131586-a61f-4186-bd1f-01e8228cfd1c) +![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) A "member" badge means this person has permissions with cleverraven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. From 2a6890ebf64737b9b1e47d5d55631700a8a65f59 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 15:53:47 -0700 Subject: [PATCH 15/37] Update development_process.md --- doc/development_process.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index f5c85ab6f463d..969a1520b1c50 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -67,7 +67,7 @@ If you've created an Issue and aren't getting much feedback, try reaching out on The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are the best ones to listen to, such as I-am-Erk, KorgGent, esotericist, Venera3, Candlebury, Renech, and more. After that, people with blue or magenta names on discord (the collaborators and moderators) often have a very good idea, and you should listen carefully to their feedback. 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 that indicates a person is a member of Cleverraven with at least a little authority, like this: -![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) +![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) 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 trying to tell you not to take their word too seriously. #### My idea was rejected, changed beyond recognition, or requires a lot more than I expected. @@ -90,8 +90,7 @@ The best way to protect yourself from getting something reverted, or rejected be #### I've started a PR and now I'm getting a ton of requested changes. Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with cleverraven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: -![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) - +![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) A "member" badge means this person has permissions with cleverraven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. 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. Just as mentioned above, **this may be the result of enthusiasm** and we might be able to meet you halfway, or we might not even mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or discord conversation, but there's no way to completely guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. It's a very small minority of PRs that become complex issues needing a lot of management and discussion like this, chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. From 873ad83a684e0321c55d886edd58502e6441e2f5 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 15:55:26 -0700 Subject: [PATCH 16/37] Update development_process.md --- doc/development_process.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 969a1520b1c50..b0a4f6282e76e 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -74,9 +74,8 @@ If a person has a "member" badge there, it usually means they speak with some au This can happen for a few reasons. If you're not sure which applies to you, feel free to ask for clarification. -* Sometimes, your idea sparks a huge conversation, and the next thing you know it seems like you're on the hook to overhaul armpit f -mechanics before you can start. *Please, feel free to mention if you feel this way*. This usually means you've hit something cool that we're all excited about. It often doesn't mean we expect you to add whatever we've started riffing on, and you're fine to just put in whatever small thing you originally wanted. We're all just huge nerds, and we know that sometimes we get carried away. -* Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws. Often it's better not to add a simplified version that will cause us problems down the road, because we then need to either revert or rework that solution to go on. If you're not able to do the harder work, you'll have to find a different idea. We won't think less of you for that. +* Sometimes, your idea sparks a huge conversation, and the next thing you know it seems like you're on the hook to overhaul armpit fart mechanics before you can start. *Please, feel free to mention if you feel this way*. This usually means you've hit something cool that we're all excited about. It often **doesn't mean we expect you to add** whatever we've started riffing on, and you're fine to just put in whatever small thing you originally wanted. We're all just huge nerds, and we know that sometimes we get carried away. +* Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws. Often it's better not to add a simplified version that will cause us problems down the road, because we then need to either revert or rework that solution to go on. If you're not able to do the harder work, you'll have to find a different idea. We won't think less of you for that, and we're sorry when this happens. It usually means we want the thing you want too. * Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. Remember that almost all the senior devs have our own pet mods; sometimes, things just go better there, and that's okay. An issue we run into occasionally is that our responses to ideas we've heard a lot of times before can be short and blunt, which can rub people the wrong way. The intent is to be matter-of-fact and completely clear. 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. Remember that, first, text doesn't convey tone well; second, we've often had this conversation twenty times already and don't want to make it seem open to debate; and third, we're all the sort of people who choose to program a complex niche game *as a hobby*. We're not all the most, um, socially skilled people. However, we can guarantee that nobody wants you to feel badly for having ideas and excitement about the game. We just cannot always be there to meet you equally. From f8d9636256ebaa55ee5dda72e0b44f5db492cef1 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 16:09:27 -0700 Subject: [PATCH 17/37] Update development_process.md --- doc/development_process.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index b0a4f6282e76e..57b45d31c2b6a 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -18,7 +18,7 @@ One of the most important concepts to understand in our project is the **experim The intention here is that if you want to *play* CDDA, you would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try hard to make sure major features in stable are playable and not a detriment to the enjoyment of the game. We try to keep stable balanced and fun. -On the other hand, in the experimental branch, we allow things to get broken. We don't want things to be broken long-term, and we rarely actively try to break them, but we don't fret it if they do. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For this reason, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. +On the other hand, in the experimental branch, we allow things to get broken. We don't want things to be broken long-term, and we rarely actively try to break them, but we don't fret it if they do. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. - First, we assess if the playtest feedback is valid. This is usually the hardest part, and it becomes harder when a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to outweigh playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. - Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. The most common way to find a solution is to think about how the mechanic in question should work in real life: for example, bow balance - a bugbear of design that plagued us for years - was finally solved by developing weak points in monster armour that could be hit with arrows. - If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix. This is also where the experimental/stable thing becomes relevant. For example, we will often leave a feature in experimental that makes the game unpleasant, because we do want that feature, and we want it working as intended. On a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. @@ -112,12 +112,12 @@ There's a common misunderstanding about the role of non-contributor players, or The short answer is, *yes, of course*, but this doesn't mean what some people might think. 1. We are not selling a product, so we don't care about mass appeal. 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*. -2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that you, the devs, like into something I prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think this mass appeal is anywhere near as obvious as it can seem from inside a drama thread. -3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a goal we have. When it's possible to do it without extra work, we're happy to keep things set as options that can be adjusted with mods, especially since most of the devs also have our own mods. However, including player-facing adjustments for every conceivable game setting is not something we want to maintain. We could write four paragraphs explaining why not, but in the end, it comes down to number 2 plus a bunch of details on managing the code. -4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. We try to keep the experimental branch of the game playable, of course, but it's not intended to represent the curated CDDA experience: experimental is often rendered very weird and imbalanced, sometimes for months at a time, as we *experiment* with things. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option when requested. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. In years of working on the project, we've seen it happen dozens upon dozens of times, and play out the same way every time. This is one of many things that can make player feedback difficult to properly assess. +2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think mass appeal, or what is fun, is anywhere near as obvious as it can seem at a glance. +3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. When it's possible to do it without extra work, we're happy to keep things set as options that can be adjusted with mods, especially since most of the devs also have our own mods. However, including player-facing adjustments for every conceivable game setting is not something we want to maintain. Explaining this could be a doc in itself, but in the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's fully our intent that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage infinite preference mods. +4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. We try to keep the experimental branch of the game playable, of course, but it's not intended to represent the curated CDDA experience: experimental is often rendered very weird and imbalanced, sometimes for months at a time, as we *experiment* with things. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. In years of working on the project, we've seen it happen dozens upon dozens of times, and play out the same way every time. This is one of many things that can make player feedback difficult to properly assess. 5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it. The general design is quite flexible, and 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. If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. -We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. It's fine if you don't agree with what we want. There are a few ways to reconcile that: you could work on a mod in mainline, 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 like Bright Nights, and help them out. You could fork the project and demonstrate your own vision for it. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. 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. +We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. 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 mainline, 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. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. 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. ##### So wait, it sounds like you're just going to do whatever you want and you don't care what the players say. @@ -142,7 +142,7 @@ To clear up a few common rumours that circulate in certain channels: #### Why did Kevin do this to me? -This merits its own section because it's such a frequent by-line in various Cataclysm communities. For the most part, for the last five or six years, Kevin has been fairly hands-off in the direct development of CDDA. He is quite present and involved in a lot of design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is a meme, but it's actually one that we consider harmful, since it obscures credit from our extremely broad base of contributors. As mentioned earlier in this document, Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides to ask nicely. If a feature was added to the game, chances are actually pretty high that someone else did it. 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, statistically it's most likely one of these people, not Kevin, changed it, and Kevin simply didn't say 'no'. +This merits its own section because it's such a frequent by-line in various Cataclysm communities. For the most part, for the last five or six years, Kevin has been fairly hands-off in the direct development of CDDA. He is quite present and involved in a lot of design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is usually started as a joke, but it obscures credit from our extremely broad base of contributors. As mentioned earlier in this document, Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides to ask nicely. If a feature was added to the game, chances are actually pretty high that someone else did it. 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, statistically it's most likely one of these people, not Kevin, changed it, and Kevin simply didn't say 'no'. ### Realism as a design goal From fbb901b1d3be6c4fde0cf2fcaad0c31f2af84590 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 16:43:24 -0700 Subject: [PATCH 18/37] Update development_process.md --- doc/development_process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/development_process.md b/doc/development_process.md index 57b45d31c2b6a..f4f4db8e6626c 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -144,6 +144,8 @@ 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. For the most part, for the last five or six years, Kevin has been fairly hands-off in the direct development of CDDA. He is quite present and involved in a lot of design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is usually started as a joke, but it obscures credit from our extremely broad base of contributors. As mentioned earlier in this document, Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides to ask nicely. If a feature was added to the game, chances are actually pretty high that someone else did it. 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, statistically it's most likely one of these people, not Kevin, changed it, and Kevin simply didn't say 'no'. +As a classic illustrative 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 collaborative process by around two dozen devs who were collectively tired of bugfixing mods none of us used. Years down the road, we continue to see this cited over and over again as an example of Kevin exerting authority on the project, when his main active role was just that he didn't stop us and agreed it was our call to make as the ones doing most of the work. Similar situations have happened dozens of times, often in cases like this when it furthers a dramatic narrative to claim that it was the unilateral action of a supreme dictator. + ### Realism as a design goal This is a much repeated buzz word. 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. This is a subtle but very important difference. Many things that would be more realistic may be nixed because of problems with play experience or play balance; for example, at time of writing, we've repeatedly shot down efforts that would make regular laundry and hygeine important, because while realistic these would be tedious and frustrating unless implemented in extremely specific ways. You can find a lot more detail about this in [the design document](https://docs.cataclysmdda.org/Lore/design-balance.html). From 12649cadc32c66caadd825f3a1919b012cd068ad Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 16:49:06 -0700 Subject: [PATCH 19/37] Update development_process.md --- doc/development_process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index f4f4db8e6626c..5205f6db78783 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -19,8 +19,8 @@ One of the most important concepts to understand in our project is the **experim The intention here is that if you want to *play* CDDA, you would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try hard to make sure major features in stable are playable and not a detriment to the enjoyment of the game. We try to keep stable balanced and fun. On the other hand, in the experimental branch, we allow things to get broken. We don't want things to be broken long-term, and we rarely actively try to break them, but we don't fret it if they do. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. -- First, we assess if the playtest feedback is valid. This is usually the hardest part, and it becomes harder when a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to outweigh playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. -- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. The most common way to find a solution is to think about how the mechanic in question should work in real life: for example, bow balance - a bugbear of design that plagued us for years - was finally solved by developing weak points in monster armour that could be hit with arrows. +- First, we assess if the playtest feedback is valid. This is usually the hardest part, and it becomes harder when news of a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. +- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's the unintended consequence of our ridiculously complex game, the most common way to find a solution is to think about how the mechanic in question should work in real life: for example, bow balance - a bugbear of design that plagued us for years - was finally solved by developing weak points in monster armour that could be hit with arrows. - If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix. This is also where the experimental/stable thing becomes relevant. For example, we will often leave a feature in experimental that makes the game unpleasant, because we do want that feature, and we want it working as intended. On a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. ### Mainline, in-repo mods, third party mods, and forks From 5efe9f13a20e38169ccfa04efba1b9c6621e68ca Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 16:58:00 -0700 Subject: [PATCH 20/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 5205f6db78783..d5457483db0ba 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -134,7 +134,7 @@ CDDA is a fork of a game called Cataclysm, developed by a guy called Whales. Ca 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](https://web.archive.org/web/20140211144953/http://www.jacehallshow.com/news/gaming/preview/20130626/ascii-goodness-living-breathing-3d-world-cataclysm-dark-days/) and [this one from about the same time](http://www.roguelikeradio.com/2013/07/episode-75-cataclysm-dark-days-ahead.html?m=1) show that the original developer team had much the same goals as we currently have 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 removed in a dedicated push around 2018-2020. To clear up a few common rumours that circulate in certain channels: -- Kevin did not steal the project from anyone. The other original devs just left, for various reasons. It's a hobby project, people come and go. There was no falling out or hard feelings. +- Kevin has always been in charge of the repo in his current capacity, even in the original oligarchy days, and there was never any sort of takeover. The other original devs just left, for various reasons. It's a hobby project, people come and go. There was no falling out or hard feelings. - Over the years we've lost a lot of developers. The reason is not as dramatic as you might think: by and large, people get bored and move on to other places. The number of major fallings-out can be counted on one hand, in over a decade of development. - We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. Community drama followed shortly afterwards, but not for related reasons. - That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and reddit shut down 3rd party apps. Nothing particularly exciting. From 7e82a03705745a396a876b0da7a635f145d67a69 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 18:52:20 -0700 Subject: [PATCH 21/37] Update doc/development_process.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jianxiang Wang (王健翔) --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index d5457483db0ba..6bd1096f65040 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -76,7 +76,7 @@ This can happen for a few reasons. If you're not sure which applies to you, fee * Sometimes, your idea sparks a huge conversation, and the next thing you know it seems like you're on the hook to overhaul armpit fart mechanics before you can start. *Please, feel free to mention if you feel this way*. This usually means you've hit something cool that we're all excited about. It often **doesn't mean we expect you to add** whatever we've started riffing on, and you're fine to just put in whatever small thing you originally wanted. We're all just huge nerds, and we know that sometimes we get carried away. * Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws. Often it's better not to add a simplified version that will cause us problems down the road, because we then need to either revert or rework that solution to go on. If you're not able to do the harder work, you'll have to find a different idea. We won't think less of you for that, and we're sorry when this happens. It usually means we want the thing you want too. -* Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. Remember that almost all the senior devs have our own pet mods; sometimes, things just go better there, and that's okay. +* Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. Remember that almost all the senior devs have their own pet mods; sometimes, things just go better there, and that's okay. An issue we run into occasionally is that our responses to ideas we've heard a lot of times before can be short and blunt, which can rub people the wrong way. The intent is to be matter-of-fact and completely clear. 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. Remember that, first, text doesn't convey tone well; second, we've often had this conversation twenty times already and don't want to make it seem open to debate; and third, we're all the sort of people who choose to program a complex niche game *as a hobby*. We're not all the most, um, socially skilled people. However, we can guarantee that nobody wants you to feel badly for having ideas and excitement about the game. We just cannot always be there to meet you equally. From 43278c3bf0ec3133be9e28b6ecafc67b72094924 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 19:04:19 -0700 Subject: [PATCH 22/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 6bd1096f65040..8708250431af4 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -37,7 +37,7 @@ This is a quick summary of the different terms we use for different groups withi * **Cleverraven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of Cleverraven and whether or not they have any official stance in what cleverraven does. Not all Cleverraven members are lead developers with merge permissions. However, anyone who is a member of Cleverraven has at least *some* official trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. -* **Lead developers** have merge permissions with Cleverraven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "lead" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. +* **Senior developers** have merge permissions with Cleverraven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. * **Developers** are members of Cleverraven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. * **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for Cleverraven, necessarily, but most of the time they know what they're talking about. * **The dev team** is a super vague term that means, roughly, "the developers and sometimes the collaborators too". From a090ac7cf00c2ca34cbe33ed834ca65646199219 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 21:01:45 -0700 Subject: [PATCH 23/37] Update development_process.md --- doc/development_process.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/development_process.md b/doc/development_process.md index 8708250431af4..c857a20b93dcc 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -23,6 +23,12 @@ On the other hand, in the experimental branch, we allow things to get broken. W - Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's the unintended consequence of our ridiculously complex game, the most common way to find a solution is to think about how the mechanic in question should work in real life: for example, bow balance - a bugbear of design that plagued us for years - was finally solved by developing weak points in monster armour that could be hit with arrows. - If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix. This is also where the experimental/stable thing becomes relevant. For example, we will often leave a feature in experimental that makes the game unpleasant, because we do want that feature, and we want it working as intended. On a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. +#### Why this format? Why not finish things before putting them in a public experimental release, or revert them if they're broken? + +Various forms of this sentiment are really common, and there are dozens of different good reasons. Let's look at just one, though, because it's possibly the most important and also the most difficult to see unless you really study how development works in the long term. + +Allowing things to get broken in experimental allows us to have big, complex projects that move the game forward in leaps and bounds. If we forced ourselves to keep experimental "fun" all the time, contributors wouldn't be free to try new things and risk causing big play balance changes. We'd never have monster weak points. We'd never have customizable sidebars. We probably wouldn't NPCs at all, possibly not even Z-levels. We wouldn't even be able to do code infrastructure changes that cause impacts on players, because things like the transition to one-second turns or the removal of charges have been woefully unpleasant to play through as we sort them out. We'd also be less welcoming to new, less experienced contributors, even if we didn't want to be, and 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 frustrating, partially complete state as we sort them out. If we were a professional full-time team, these things would probably progress a bit faster, but we work on volunteer time, and this is the system we've found that allows volunteers to develop systems that would be at home in a professional game, while having only a few hours a week of their time to contribute. + ### Mainline, in-repo mods, third party mods, and forks 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; you just probably don't treat it as one. This version, which we often call 'mainline' here, is the one we curate and treat the way we want to treat, usually with about 50-100 contributors from all over the internet helping out at any given time. @@ -158,6 +164,12 @@ 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 possible 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 learn how to code and to work on it yourself. Chances are this is not as difficult as it sounds. However, if you just can't do that for some reason, 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 might have a lot of sway in convincing a coder to do them a favour. +#### Why did X system get implemented with Y, but not Z? + +For example, why did science equipment get added but you could only loot it in one location? Why did anvils get overhauled in a way that made it hard to craft them? + +This is a subset to the question above. The answer is, because the person implementing it didn't want their PR to explode into a whole bunch of extra features. This can happen for many reasons, but the most common is probably that the person implementing the PR needed that infrastructure for something else they were doing; they wanted to do it right, but they didn't want to get into the play balance of working out every other step down the road. 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: add science equipment to more spawn lists. Add some new ways to obtain anvils. 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. + ## The Bottom Line Did you actually read all that, or just scroll down? Massive kudos if you read it. From 6ba6a361a6b249d528d1b8691958e399058c9e06 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 21:03:25 -0700 Subject: [PATCH 24/37] Update development_process.md --- doc/development_process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index c857a20b93dcc..0cbe1ddbc5ed2 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -44,10 +44,10 @@ This is a quick summary of the different terms we use for different groups withi * **Cleverraven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of Cleverraven and whether or not they have any official stance in what cleverraven does. Not all Cleverraven members are lead developers with merge permissions. However, anyone who is a member of Cleverraven has at least *some* official trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. * **Senior developers** have merge permissions with Cleverraven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. -* **Developers** are members of Cleverraven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. +* **Developers** are members of Cleverraven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. * **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for Cleverraven, necessarily, but most of the time they know what they're talking about. * **The dev team** is a super vague term that means, roughly, "the developers and sometimes the collaborators too". -* **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. +* **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on discord. * **Core contributors** is another super vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". * **Players** are the people whose lives we try to ruin, who somehow keep coming back for more. What is their deal? We may never know. From b25bb353fa6b9100ebd78c5361f7d759b85f941a Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 21:31:43 -0700 Subject: [PATCH 25/37] Update development_process.md --- doc/development_process.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 0cbe1ddbc5ed2..67e97bf2fa413 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -62,7 +62,7 @@ This section is going to be super long, and you're welcome to read it all if you ### What if my contributions aren't accepted? -If what you're doing is simple, like fixing typos, 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 higher up in the project. There are two good ways to do that: either create an Issue post on GitHub, or chat in [the developer discord](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel 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 to the project. +If what you're doing is simple, like adding an item or a bit of dialogue, 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 higher up in the project. There are two good ways to do that: either create an Issue post on GitHub, or chat in [the developer discord](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel 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 to the project. By and large, 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 basically skip this entire document. You'll be fine. It's already a small minority of things that turn out to not work out and need to be re-thought, and if you're easygoing about that risk then you have nothing to worry about. If that possibility concerns you though, reading on may help you to figure out how to limit the risk of creating something only to find it won't get in, or needs a lot more work than you thought. @@ -109,6 +109,14 @@ If you're on the developer discord to talk about development, it's very difficul 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. +### I'd like to change an existing feature/npc/faction but I don't know who owns it to ask about it + +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. This can be the most dramatic in the case of NPCs and factions, where it feels like they really belong to the person who made them or who last overhauled them, but it's an attitude we'd really like to try to dispel. + +> I'm going to break the "dev team" voice for this section and start speaking as Erk, the person who's probably added the most NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. As a rule of thumb, I think future changes should try to respect the NPC as they exist in the game, but if someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all Rubik's existing dialogue very well. I might offer some feedback on voice, and if asked I might comment on how it differs from my vision, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. + +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. + ### How does player feedback affect the project's development? 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, and it's definitely not true; it should not be a reason to decide not to contribute. First, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it as much as you like! However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. @@ -150,7 +158,7 @@ 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. For the most part, for the last five or six years, Kevin has been fairly hands-off in the direct development of CDDA. He is quite present and involved in a lot of design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is usually started as a joke, but it obscures credit from our extremely broad base of contributors. As mentioned earlier in this document, Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides to ask nicely. If a feature was added to the game, chances are actually pretty high that someone else did it. 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, statistically it's most likely one of these people, not Kevin, changed it, and Kevin simply didn't say 'no'. -As a classic illustrative 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 collaborative process by around two dozen devs who were collectively tired of bugfixing mods none of us used. Years down the road, we continue to see this cited over and over again as an example of Kevin exerting authority on the project, when his main active role was just that he didn't stop us and agreed it was our call to make as the ones doing most of the work. Similar situations have happened dozens of times, often in cases like this when it furthers a dramatic narrative to claim that it was the unilateral action of a supreme dictator. +As a classic illustrative 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 collaborative process 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 over and over again as an example of Kevin exerting authority on the project, when his main active role was just that he didn't stop us and agreed it was our call to make as the ones doing most of the work. Similar situations have happened dozens of times, often in cases like this when it furthers a dramatic narrative to claim that it was the unilateral action of a supreme dictator. ### Realism as a design goal From 8d411d55be13de2d0937c9685bbdd41cccafa000 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 21:33:02 -0700 Subject: [PATCH 26/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 67e97bf2fa413..0f9fb5d5bc84e 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -113,7 +113,7 @@ If someone is telling you they got banned from "devcord" for nothing at all with 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. This can be the most dramatic in the case of NPCs and factions, where it feels like they really belong to the person who made them or who last overhauled them, but it's an attitude we'd really like to try to dispel. -> I'm going to break the "dev team" voice for this section and start speaking as Erk, the person who's probably added the most NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. As a rule of thumb, I think future changes should try to respect the NPC as they exist in the game, but if someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all Rubik's existing dialogue very well. I might offer some feedback on voice, and if asked I might comment on how it differs from my vision, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. +> I'm going to break the "dev team" voice for this section and start speaking as Erk, one of the people who has added a ton of NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. As a rule of thumb, I think future changes should try to respect the NPC as they exist in the game, but if someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all Rubik's existing dialogue very well. I might offer some feedback on voice, and if asked I might comment on how it differs from my vision, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. 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. From 55519ef68cd771ed63b6c820284679f1f74aa47a Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 21:38:33 -0700 Subject: [PATCH 27/37] Update development_process.md --- doc/development_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development_process.md b/doc/development_process.md index 0f9fb5d5bc84e..e2701ce0d7020 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -113,7 +113,7 @@ If someone is telling you they got banned from "devcord" for nothing at all with 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. This can be the most dramatic in the case of NPCs and factions, where it feels like they really belong to the person who made them or who last overhauled them, but it's an attitude we'd really like to try to dispel. -> I'm going to break the "dev team" voice for this section and start speaking as Erk, one of the people who has added a ton of NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. As a rule of thumb, I think future changes should try to respect the NPC as they exist in the game, but if someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all Rubik's existing dialogue very well. I might offer some feedback on voice, and if asked I might comment on how it differs from my vision, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. +> I'm going to break the "dev team" voice for this section and start speaking as Erk, one of the people who has added a ton of NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. As a rule of thumb, I think future changes should try to respect the NPC as they exist in the game, but if someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all their existing dialogue very well. I might offer some feedback on voice, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps, etc. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. 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. From 8c433be56d00cbae439675a6226f19d941d5d835 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 22:40:23 -0700 Subject: [PATCH 28/37] Update development_process.md --- doc/development_process.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index e2701ce0d7020..c73e6290119c6 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -2,13 +2,13 @@ **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, as individuals are welcome to disagree with the team stance. +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, as individuals are welcome to disagree with the team stance. This document assumes you have a basic understanding how GitHub works. Please see the [guide for new contributors](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html), which talks about some of the common ideas we hear for the project and offers reasons about why they might not have been added yet. [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. ## The basic concept -At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the Cleverraven group that runs this branch of the code. We (as in, all the members of the development team) often have different ideas of what's fun or good, and we put those things in our own mods (eg Aftershock, Magiclysm, and Dark Days of the Dead) if we can't work them into the main game. 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. He tends to have stronger opinions about the infrastructure of the project, as one might expect from a software engineer working for more than a decade on a single massive open-source project. +At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch of the code. We (as in, all the members of the development team) often have different ideas of what's fun or good, and we put those things in our own mods (eg Aftershock, Magiclysm, and Dark Days of the Dead) if we can't work them into the main game. 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. He tends to have stronger opinions about the infrastructure of the project, as one might expect from a software engineer working for more than a decade on a single massive open-source project. ## The structure of the project itself @@ -41,11 +41,11 @@ Cataclysm: DDA is one version of the 'cataclysm' source code. There are many ot 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, with only a few exceptions, because as a volunteer project we mostly treat this as an open forum for discussion, not a project with a strict chain of command. Unfortunately, this can be a bit confusing. -* **Cleverraven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of Cleverraven and whether or not they have any official stance in what cleverraven does. Not all Cleverraven members are lead developers with merge permissions. However, anyone who is a member of Cleverraven has at least *some* official trust and experience with the project. +* **CleverRaven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official stance in what CleverRaven does. Not all CleverRaven members are lead developers with merge permissions. However, anyone who is a member of CleverRaven has at least *some* official trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. -* **Senior developers** have merge permissions with Cleverraven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. -* **Developers** are members of Cleverraven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. -* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for Cleverraven, necessarily, but most of the time they know what they're talking about. +* **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. +* **Developers** are members of CleverRaven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. +* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven, necessarily, but most of the time they know what they're talking about. * **The dev team** is a super vague term that means, roughly, "the developers and sometimes the collaborators too". * **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on discord. * **Core contributors** is another super vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". @@ -72,9 +72,9 @@ If you've created an Issue and aren't getting much feedback, try reaching out on The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are the best ones to listen to, such as I-am-Erk, KorgGent, esotericist, Venera3, Candlebury, Renech, and more. After that, people with blue or magenta names on discord (the collaborators and moderators) often have a very good idea, and you should listen carefully to their feedback. 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 that indicates a person is a member of Cleverraven with at least a little authority, like this: +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 that indicates a person is a member of CleverRaven with at least a little authority, like this: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) -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 trying to tell you not to take their word too seriously. +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 trying to tell you not to take their word too seriously. #### My idea was rejected, changed beyond recognition, or requires a lot more than I expected. @@ -94,9 +94,9 @@ The best way to protect yourself from getting something reverted, or rejected be #### I've started a PR and now I'm getting a ton of requested changes. -Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with cleverraven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: +Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with CleverRaven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) -A "member" badge means this person has permissions with cleverraven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. +A "member" badge means this person has permissions with CleverRaven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. 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. Just as mentioned above, **this may be the result of enthusiasm** and we might be able to meet you halfway, or we might not even mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or discord conversation, but there's no way to completely guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. It's a very small minority of PRs that become complex issues needing a lot of management and discussion like this, chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. From d79d5729ad9aa4679924957ee95be8078844014c Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 22:54:46 -0700 Subject: [PATCH 29/37] Update development_process.md --- doc/development_process.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index c73e6290119c6..56f39cbe47652 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -8,7 +8,7 @@ This document assumes you have a basic understanding how GitHub works. Please s ## The basic concept -At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch of the code. We (as in, all the members of the development team) often have different ideas of what's fun or good, and we put those things in our own mods (eg Aftershock, Magiclysm, and Dark Days of the Dead) if we can't work them into the main game. 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. He tends to have stronger opinions about the infrastructure of the project, as one might expect from a software engineer working for more than a decade on a single massive open-source project. +At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch 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. ## The structure of the project itself @@ -18,36 +18,36 @@ One of the most important concepts to understand in our project is the **experim The intention here is that if you want to *play* CDDA, you would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try hard to make sure major features in stable are playable and not a detriment to the enjoyment of the game. We try to keep stable balanced and fun. -On the other hand, in the experimental branch, we allow things to get broken. We don't want things to be broken long-term, and we rarely actively try to break them, but we don't fret it if they do. We often allow trusted contributors to mess something up just to see what happens, or to put in a partially complete project in order to collect data on what's needed for the next phase. Not everyone likes being a guinea pig! That's fine! That's why we try to put out a stable every year or two. People can also choose to play snapshots of experimental from before certain changes went in. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. +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. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. - First, we assess if the playtest feedback is valid. This is usually the hardest part, and it becomes harder when news of a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. -- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's the unintended consequence of our ridiculously complex game, the most common way to find a solution is to think about how the mechanic in question should work in real life: for example, bow balance - a bugbear of design that plagued us for years - was finally solved by developing weak points in monster armour that could be hit with arrows. -- If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix. This is also where the experimental/stable thing becomes relevant. For example, we will often leave a feature in experimental that makes the game unpleasant, because we do want that feature, and we want it working as intended. On a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. +- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's the unintended consequence of our ridiculously complex game, the most common way to find a solution is to think about how the mechanic in question should work in real life. +- If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. #### Why this format? Why not finish things before putting them in a public experimental release, or revert them if they're broken? -Various forms of this sentiment are really common, and there are dozens of different good reasons. Let's look at just one, though, because it's possibly the most important and also the most difficult to see unless you really study how development works in the long term. +Various forms of this sentiment are really common, and 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 study how development works in the long term. -Allowing things to get broken in experimental allows us to have big, complex projects that move the game forward in leaps and bounds. If we forced ourselves to keep experimental "fun" all the time, contributors wouldn't be free to try new things and risk causing big play balance changes. We'd never have monster weak points. We'd never have customizable sidebars. We probably wouldn't NPCs at all, possibly not even Z-levels. We wouldn't even be able to do code infrastructure changes that cause impacts on players, because things like the transition to one-second turns or the removal of charges have been woefully unpleasant to play through as we sort them out. We'd also be less welcoming to new, less experienced contributors, even if we didn't want to be, and 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 frustrating, partially complete state as we sort them out. If we were a professional full-time team, these things would probably progress a bit faster, but we work on volunteer time, and this is the system we've found that allows volunteers to develop systems that would be at home in a professional game, while having only a few hours a week of their time to contribute. +Allowing things to get broken in experimental allows us to have big, complex projects that move the game forward in leaps and bounds. If we forced ourselves to keep experimental "fun" all the time, contributors wouldn't be free to try new things and risk big play balance changes. Most of the complex things that make CDDA unique would have been almost impossible to create. We'd be less welcoming to new, less experienced contributors, even if we didn't want to, and 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 frustrating, partially complete state as we sort them out. If we were a professional full-time team, these things would probably progress a bit faster, but we work on volunteer time, and this is the system we've found that allows volunteers to develop systems that would be at home in a professional game, while having only a few hours a week of their time to contribute. ### Mainline, in-repo mods, third party mods, and forks -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; you just probably don't treat it as one. This version, which we often call 'mainline' here, is the one we curate and treat the way we want to treat, usually with about 50-100 contributors from all over the internet helping out at any given time. +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". -* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include in mainline. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to the developers of the game who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. If you leave and stop maintaining it, we may allow someone else to take it over when it breaks, or we might hide and eventually remove it. If you came back and wanted to revive it, we'd probably let you. -* **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. To our knowledge there's no central repository of third party mods, which seems like a bit of a shame. -* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. From our perspective, there's no rivalry here. We're very happy BN exists and we want them to thrive. Sometimes they use our source code and vice versa, due to the open nature of the license. +* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to the developers of the game who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. +* **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. +* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. ### Project roles -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, with only a few exceptions, because as a volunteer project we mostly treat this as an open forum for discussion, not a project with a strict chain of command. Unfortunately, this can be a bit confusing. +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. Unfortunately, this can be a bit confusing. * **CleverRaven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official stance in what CleverRaven does. Not all CleverRaven members are lead developers with merge permissions. However, anyone who is a member of CleverRaven has at least *some* official trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. -* **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. I-am-Erk seems to be in this role for some reason, though he can't really figure out how it happened nor why he hasn't run away yet. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. +* **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. * **Developers** are members of CleverRaven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. * **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven, necessarily, but most of the time they know what they're talking about. * **The dev team** is a super vague term that means, roughly, "the developers and sometimes the collaborators too". -* **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on discord. +* **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on Discord. * **Core contributors** is another super vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". * **Players** are the people whose lives we try to ruin, who somehow keep coming back for more. What is their deal? We may never know. From 8866d84967f423ecd9fc814d4e9dc722b5558e99 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Thu, 23 May 2024 23:34:10 -0700 Subject: [PATCH 30/37] Update development_process.md --- doc/development_process.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 56f39cbe47652..ba48d394feb58 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -16,24 +16,24 @@ At its core, CDDA is a survival simulation game. [The design doc outlines what 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 would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try hard to make sure major features in stable are playable and not a detriment to the enjoyment of the game. We try to keep stable balanced and fun. +The intention here is that if you want to *play* CDDA, you would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try to keep stable balanced and fun. -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. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's look under the hood and see how we respond to playtest feedback. -- First, we assess if the playtest feedback is valid. This is usually the hardest part, and it becomes harder when news of a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. -- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's the unintended consequence of our ridiculously complex game, the most common way to find a solution is to think about how the mechanic in question should work in real life. -- If the behaviour is intended, we might consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. +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. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's examine how we handle playtest feedback. +- First, we assess if the playtest feedback is valid. This is hard, and it becomes harder when news of a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. +- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life. +- If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. #### Why this format? Why not finish things before putting them in a public experimental release, or revert them if they're broken? Various forms of this sentiment are really common, and 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 study how development works in the long term. -Allowing things to get broken in experimental allows us to have big, complex projects that move the game forward in leaps and bounds. If we forced ourselves to keep experimental "fun" all the time, contributors wouldn't be free to try new things and risk big play balance changes. Most of the complex things that make CDDA unique would have been almost impossible to create. We'd be less welcoming to new, less experienced contributors, even if we didn't want to, and 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 frustrating, partially complete state as we sort them out. If we were a professional full-time team, these things would probably progress a bit faster, but we work on volunteer time, and this is the system we've found that allows volunteers to develop systems that would be at home in a professional game, while having only a few hours a week of their time to contribute. +Allowing things to get broken in experimental allows us to have big, complex projects that move the game forward in leaps and bounds. If we forced ourselves to keep experimental smooth and playable all the time, contributors wouldn't be free to try new things and risk big play balance changes. Most of the complex things that make CDDA unique would have been almost impossible to create. We'd be less welcoming to new, less experienced contributors, even if we didn't want to, and 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 frustrating, partially complete state as we sort them out. If we were a professional full-time team, these things would probably progress a bit faster, but we work on volunteer time, and this is the system we've found that allows volunteers to develop systems that would be at home in a professional game, while having only a few hours a week of their time to contribute. ### Mainline, in-repo mods, third party mods, and forks 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". -* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to the developers of the game who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. +* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to devs who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. * **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. * **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. @@ -46,9 +46,9 @@ This is a quick summary of the different terms we use for different groups withi * **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. * **Developers** are members of CleverRaven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. * **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven, necessarily, but most of the time they know what they're talking about. -* **The dev team** is a super vague term that means, roughly, "the developers and sometimes the collaborators too". +* **The dev team** is a vague term that means, roughly, "the developers and sometimes the collaborators too". * **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on Discord. -* **Core contributors** is another super vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". +* **Core contributors** is another vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". * **Players** are the people whose lives we try to ruin, who somehow keep coming back for more. What is their deal? We may never know. ## Helpful tips for prospective contributors @@ -58,11 +58,11 @@ This section is going to be super long, and you're welcome to read it all if you 1. Most simple, reasonable contributions get accepted. For larger projects, you might want to get more experience with the project or clear it with a developer first. 2. If it sounds like your small job is being turned into a big unmanageable job, check if the ideas being thrown around are things *you* have to do, or just people getting excited. Usually it's just excitement, it means you have a cool idea but not that you need to do a bunch more stuff. 3. If you're getting negative feedback or being told you have to do something a certain way, make sure it's someone with authority before you start feeling discouraged. -4. Please don't take it personally if a developer gives you a short, gruff answer. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact, not to be unkind. +4. Please don't take it personally if you receive a short, direct response on a PR or issue. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact, not to be unkind. ### What if my contributions aren't accepted? -If what you're doing is simple, like adding an item or a bit of dialogue, 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 higher up in the project. There are two good ways to do that: either create an Issue post on GitHub, or chat in [the developer discord](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel 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 to the project. +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 higher up in the project. There are two good ways to do that: either create an Issue post on GitHub, or chat in [the developer discord](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel 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 to the project. By and large, 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 basically skip this entire document. You'll be fine. It's already a small minority of things that turn out to not work out and need to be re-thought, and if you're easygoing about that risk then you have nothing to worry about. If that possibility concerns you though, reading on may help you to figure out how to limit the risk of creating something only to find it won't get in, or needs a lot more work than you thought. From bd4598696de9f1098809c04e17b03924fa787e03 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 10:20:57 -0700 Subject: [PATCH 31/37] Ongoing brevity edits and moved some stuff to footnotes --- doc/development_process.md | 67 ++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 28 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index ba48d394feb58..f086032c23c68 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -8,7 +8,7 @@ This document assumes you have a basic understanding how GitHub works. Please s ## The basic concept -At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch 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. +At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch 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[^code]. ## The structure of the project itself @@ -19,8 +19,8 @@ One of the most important concepts to understand in our project is the **experim The intention here is that if you want to *play* CDDA, you would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try to keep stable balanced and fun. 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. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's examine how we handle playtest feedback. -- First, we assess if the playtest feedback is valid. This is hard, and it becomes harder when news of a change is circulated to people that haven't yet tested the change. There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. -- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life. +- First, we assess if the playtest feedback is valid. This is hard, and it becomes harder when news of a change is circulated to people that haven't yet tested the change.[^whytheory] +- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life.[^bows] - If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. #### Why this format? Why not finish things before putting them in a public experimental release, or revert them if they're broken? @@ -43,7 +43,7 @@ This is a quick summary of the different terms we use for different groups withi * **CleverRaven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official stance in what CleverRaven does. Not all CleverRaven members are lead developers with merge permissions. However, anyone who is a member of CleverRaven has at least *some* official trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. -* **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop. Some of the senior devs have gold names on Discord, but because we love confusion, most do not. +* **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop.[^erk] Some of the senior devs have gold names on Discord, but because we love confusion, most do not. * **Developers** are members of CleverRaven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. * **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven, necessarily, but most of the time they know what they're talking about. * **The dev team** is a vague term that means, roughly, "the developers and sometimes the collaborators too". @@ -62,15 +62,15 @@ This section is going to be super long, and you're welcome to read it all if you ### What if my contributions aren't accepted? -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 higher up in the project. There are two good ways to do that: either create an Issue post on GitHub, or chat in [the developer discord](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel 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 to the project. +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](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel, or post in [the discourse forum](https://discourse.cataclysmdda.org/)[^discourse] 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 to the project. -By and large, 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 basically skip this entire document. You'll be fine. It's already a small minority of things that turn out to not work out and need to be re-thought, and if you're easygoing about that risk then you have nothing to worry about. If that possibility concerns you though, reading on may help you to figure out how to limit the risk of creating something only to find it won't get in, or needs a lot more work than you thought. +By and large, 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 basically 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 project like this. -If you've created an Issue 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. +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. #### What if different people have different opinions of my idea? -The ultimate authority is Kevin Granade, as project lead. After him, the developers (green and gold names on discord) are the best ones to listen to, such as I-am-Erk, KorgGent, esotericist, Venera3, Candlebury, Renech, and more. After that, people with blue or magenta names on discord (the collaborators and moderators) often have a very good idea, and you should listen carefully to their feedback. 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. +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 that indicates a person is a member of CleverRaven with at least a little authority, like this: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) @@ -81,61 +81,59 @@ If a person has a "member" badge there, it usually means they speak with some au This can happen for a few reasons. If you're not sure which applies to you, feel free to ask for clarification. * Sometimes, your idea sparks a huge conversation, and the next thing you know it seems like you're on the hook to overhaul armpit fart mechanics before you can start. *Please, feel free to mention if you feel this way*. This usually means you've hit something cool that we're all excited about. It often **doesn't mean we expect you to add** whatever we've started riffing on, and you're fine to just put in whatever small thing you originally wanted. We're all just huge nerds, and we know that sometimes we get carried away. -* Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws. Often it's better not to add a simplified version that will cause us problems down the road, because we then need to either revert or rework that solution to go on. If you're not able to do the harder work, you'll have to find a different idea. We won't think less of you for that, and we're sorry when this happens. It usually means we want the thing you want too. -* Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. Remember that almost all the senior devs have their own pet mods; sometimes, things just go better there, and that's okay. +* Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws that will cause us problems down the road. If you're not able to do the harder work, you may have to find a different thing to work on. We won't think less of you for that, and we're sorry when this happens. +* Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. -An issue we run into occasionally is that our responses to ideas we've heard a lot of times before can be short and blunt, which can rub people the wrong way. The intent is to be matter-of-fact and completely clear. 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. Remember that, first, text doesn't convey tone well; second, we've often had this conversation twenty times already and don't want to make it seem open to debate; and third, we're all the sort of people who choose to program a complex niche game *as a hobby*. We're not all the most, um, socially skilled people. However, we can guarantee that nobody wants you to feel badly for having ideas and excitement about the game. We just cannot always be there to meet you equally. +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 definitely not more kind 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 can guarantee that nobody wants you to feel badly for having ideas and excitement about the game.[^ajoke] #### I've heard a lot of things get merged to the project, then reverted. -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 a lot. 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. For example, a PR might be reverted because the code has unforseen consequences that create bugs that will be very hard to fix; or, it might have attribution errors. It's very important to understand that on our end, **we consider reversions a failure of the dev team**. They aren't your fault as a contributor: if something is getting reverted it's because we failed to properly review it. They don't mean that your contributions aren't valued. They mean that we messed up and we're fixing it as best we can. The fact that it got merged in the first place often means that it's appropriate to the game, but we strongly advise not working on it further until you've confirmed that. +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 on github or discord with developers and make sure it's appropriate, (2) [get someone to review your PR before it's merged]([https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md](https://docs.cataclysmdda.org/reviewing_PR_guide.html)), 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. +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]([https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md](https://docs.cataclysmdda.org/reviewing_PR_guide.html)), 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. #### I've started a PR and now I'm getting a ton of requested changes. -Sometimes, this is just a consequence of learning the system. GitHub is hard to use, and our code is complex and messy. 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 with CleverRaven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: +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 with CleverRaven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) -A "member" badge means this person has permissions with CleverRaven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. +A "member" badge means this person has permissions with CleverRaven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. Just as mentioned above, **this may be the result of enthusiasm** and we might be able to meet you halfway, or we might not even mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or discord conversation, but there's no way to completely guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. It's a very small minority of PRs that become complex issues needing a lot of management and discussion like this, chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. +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. Just as mentioned above, **this may be the result of enthusiasm**, and we might not mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or Discord conversation, but there's no way to guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. Chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. The bigger your contribution is, the more important it becomes to get clearance. #### You keep suggesting the discord, but I've heard it's really strict. We don't think so, but obviously we're biased. First, make sure you're looking at [the developer discord](https://discord.gg/hqWgHC8TKY) 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. If you're worried about getting in trouble for your memes or fun chat times, we suggest just going to [the community discord](https://discord.gg/byxwnAU +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 first[^spam]. If you're worried about getting in trouble for your memes or fun chat times, we suggest just going to [the community discord](https://discord.gg/byxwnAU ), 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 not the place to go for memes about cargo socks. It *is* 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. ### I'd like to change an existing feature/npc/faction but I don't know who owns it to ask about it -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. This can be the most dramatic in the case of NPCs and factions, where it feels like they really belong to the person who made them or who last overhauled them, but it's an attitude we'd really like to try to dispel. +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.[^npcs] 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. -> I'm going to break the "dev team" voice for this section and start speaking as Erk, one of the people who has added a ton of NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. As a rule of thumb, I think future changes should try to respect the NPC as they exist in the game, but if someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all their existing dialogue very well. I might offer some feedback on voice, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps, etc. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. - -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. +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![^erkaside] 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. ### How does player feedback affect the project's development? -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, and it's definitely not true; it should not be a reason to decide not to contribute. First, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it as much as you like! However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. +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, and it's definitely not true; it should not be a reason to decide not to contribute.[^feedback] However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. #### Do we care about the players? The short answer is, *yes, of course*, but this doesn't mean what some people might think. -1. We are not selling a product, so we don't care about mass appeal. 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*. +1. We are not selling a product, so we don't care about mass appeal or how many people play the game.[^massappeal] 2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think mass appeal, or what is fun, is anywhere near as obvious as it can seem at a glance. -3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. When it's possible to do it without extra work, we're happy to keep things set as options that can be adjusted with mods, especially since most of the devs also have our own mods. However, including player-facing adjustments for every conceivable game setting is not something we want to maintain. Explaining this could be a doc in itself, but in the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's fully our intent that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage infinite preference mods. -4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. We try to keep the experimental branch of the game playable, of course, but it's not intended to represent the curated CDDA experience: experimental is often rendered very weird and imbalanced, sometimes for months at a time, as we *experiment* with things. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. In years of working on the project, we've seen it happen dozens upon dozens of times, and play out the same way every time. This is one of many things that can make player feedback difficult to properly assess. -5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it. The general design is quite flexible, and 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. If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. +3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. Including player-facing adjustments for every conceivable game setting is not something we want to maintain. Explaining this could be a doc in itself, but in the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's fully our intent that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage infinite preference mods. +4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. See [the section on experimental/stable](#experimentalstable). Experimental is often rendered very weird and imbalanced, sometimes for months at a time. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. +5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it.[^venera] If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. -We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also allowing side projects and flavour tweaks to be part of mainline. 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 mainline, 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. The ability to go your own way if you disagree is one of the strongest assets we have, it's not a problem if you want to do your own thing. A healthy open-source project should have a few good forks. 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. +We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also 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. ##### So wait, it sounds like you're just going to do whatever you want and you don't care what the players say. -If you took that away from the above, and a few people definitely did, we'll probably never see eye-to-eye. However, we do actually care what players say. We all love talking to the players. Seriously, we do, that's why we do so much of it. Players, even players who never have and never will contribute directly to the game, have *wildly* altered the course of DDA's development in countless ways. It's just that this has not, and never will, manifest in Kevin deciding to shift design goals because a bunch of people angrily demanded it. Very often, constructive discussion with players manifests in our overall *goals* remaining the same, but us reaching a new agreement in *how to reach those goals*. Sometimes, of course, we will listen to many well-reasoned arguments from intelligent and passionate people, and still not change our minds. That is, of course, because 'listening' and 'caring about what you say' is not the same as 'doing what we're told to do'. We've learned over the years that for some, this is not 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. +If you took that away from the above, and a few people definitely did, we'll probably never see eye-to-eye. However, we do actually care what players say. We all really do love talking to the players. It's just that this has not, and never will, manifest in us deciding to shift design goals because a bunch of people demanded it. Very often, constructive discussion with players manifests in our overall *goals* remaining the same, but us reaching a new agreement in *how to reach those goals*. Sometimes, of course, we will listen to many well-reasoned arguments, and still not change our minds. That is because 'listening' and 'caring about what you say' is not the same as 'doing what we're told'. We've learned over the years that for some, this is not 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. ## Supplemental Material @@ -183,3 +181,16 @@ This is a subset to the question above. The answer is, because the person imple 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. + +[^code]: 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. +[^whytheory]: There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. +[^bows]: 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. +[^erk]: This happened to I-am-Erk somehow and he's still not sure why he hasn't run away screaming. +[^discourse]: 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. +[^ajoke]: 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. +[^spam]: Unless you're a spambot, but then how are you reading this? +[^npcs]: 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. +[^erkaside]: I'm going to break the "dev team" voice for this section and start speaking as Erk, one of the people who has added a ton of NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. If someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all their existing dialogue very well. I might offer some feedback on voice, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps, etc. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. The only exception is when it impacts long-term planning for the game. Note that this isn't how all contributors feel about their NPCs and that's another reason it's a good idea to check in first. +[^feedback]: Also, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it however you like! +[^massappeal]: 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*. +[^venera]: The general design is quite flexible, and 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. From d4fee0eb3dde1b93db8cda77fe64c1d1207b85b3 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 10:53:39 -0700 Subject: [PATCH 32/37] adjust order and add a table of contents --- doc/development_process.md | 57 ++++++++++++++++++++++++++++---------- 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index f086032c23c68..ce7bcbe95f227 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -6,11 +6,36 @@ This guide is intended to describe how the Cataclysm: Dark Days Ahead project is This document assumes you have a basic understanding how GitHub works. Please see the [guide for new contributors](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html), which talks about some of the common ideas we hear for the project and offers reasons about why they might not have been added yet. [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. +## Table of Contents + +* [The basic concept](#The-basic-concept) +* [The structure of the project](#The-structure-of-the-project) +* * [Experimental/Stable](#experimentalstable) +* * * [Why this format?](#Why-this-format) +* * [Mainline, in-repo mods, third party mods, and forks](#mainline-in-repo-mods-third-party-mods-and-forks) +* * [Project roles](#Project-roles) +* [FAQ for prospective contributors](#FAQ-for-prospective-contributors) +* * [How can I make sure my contribution will be accepted?](#How-can-I-make-sure-my-contribution-will-be-accepted) +* * * [What if different people have different opinions of my idea?](#What-if-different-people-have-different-opinions-of-my-idea) +* * * [How do I deal with a ton of comments and suggestions to my idea?](#How-do-I-deal-with-a-ton-of-comments-and-suggestions-to-my-idea) +* * * [Do a lot of things get merged to the project, then reverted?](#Do-a-lot-of-things-get-merged-to-the-project-then-reverted) +* * * [Am I allowed to do what I want with an existing NPC/faction/feature?](#Am-I-allowed-to-do-what-I-want-with-an-existing-NPCfactionfeature) +* * [Is the Discord strict?](#Is-the-Discord-strict) +* * [How does player feedback affect the project's development?](#How-does-player-feedback-affect-the-projects-development) +* * * [Do we care about the players?](#Do-we-care-about-the-players) +* [Supplemental Material](#Supplemental-Material) +* * [A Very Brief History of DDA](#A-Very-Brief-History-of-DDA) +* * * [Why did Kevin do this to me?](#Why-did-Kevin-do-this-to-me) +* * [Realism as a design goal](#Realism-as-a-design-goal) +* * [Why did X system get worked on while the more important Y system didn't](#Why-did-X-system-get-worked-on-while-the-more-important-Y-system-didnt) +* * * [Why did X system get implemented with Y, but not Z](#Why-did-X-system-get-implemented-with-Y-but-not-Z) +* [The Bottom Line](#The-Bottom-Line) + ## The basic concept At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch 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[^code]. -## The structure of the project itself +## The structure of the project ### Experimental/Stable @@ -23,7 +48,8 @@ On the other hand, in the experimental branch, we allow things to get broken. W - Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life.[^bows] - If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. -#### Why this format? Why not finish things before putting them in a public experimental release, or revert them if they're broken? +#### Why this format? +**Why not finish things before putting them in a public experimental release, or revert them if they're broken?** Various forms of this sentiment are really common, and 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 study how development works in the long term. @@ -51,16 +77,16 @@ This is a quick summary of the different terms we use for different groups withi * **Core contributors** is another vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". * **Players** are the people whose lives we try to ruin, who somehow keep coming back for more. What is their deal? We may never know. -## Helpful tips for prospective contributors +## FAQ for prospective contributors -This section is going to be super long, and you're welcome to read it all if you like, but here's the most important TL;DR points: +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: 1. Most simple, reasonable contributions get accepted. For larger projects, you might want to get more experience with the project or clear it with a developer first. 2. If it sounds like your small job is being turned into a big unmanageable job, check if the ideas being thrown around are things *you* have to do, or just people getting excited. Usually it's just excitement, it means you have a cool idea but not that you need to do a bunch more stuff. 3. If you're getting negative feedback or being told you have to do something a certain way, make sure it's someone with authority before you start feeling discouraged. 4. Please don't take it personally if you receive a short, direct response on a PR or issue. Tone doesn't convey well in text, but the intent is to be completely clear and matter-of-fact, not to be unkind. -### What if my contributions aren't accepted? +### How can I make sure my contribution will be accepted? 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](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel, or post in [the discourse forum](https://discourse.cataclysmdda.org/)[^discourse] 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 to the project. @@ -86,13 +112,13 @@ This can happen for a few reasons. If you're not sure which applies to you, fee 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 definitely not more kind 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 can guarantee that nobody wants you to feel badly for having ideas and excitement about the game.[^ajoke] -#### I've heard a lot of things get merged to the project, then reverted. +#### Do a lot of things get merged to the project, then reverted? 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]([https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md](https://docs.cataclysmdda.org/reviewing_PR_guide.html)), 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. -#### I've started a PR and now I'm getting a ton of requested changes. +#### How do I deal with a ton of comments and suggestions to my idea? 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 with CleverRaven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) @@ -100,7 +126,13 @@ A "member" badge means this person has permissions with CleverRaven and so has a 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. Just as mentioned above, **this may be the result of enthusiasm**, and we might not mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or Discord conversation, but there's no way to guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. Chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. The bigger your contribution is, the more important it becomes to get clearance. -#### You keep suggesting the discord, but I've heard it's really strict. +#### Am I allowed to do what I want with an existing NPC/faction/feature? + +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.[^npcs] 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![^erkaside] 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. + +### Is the Discord strict? We don't think so, but obviously we're biased. First, make sure you're looking at [the developer discord](https://discord.gg/hqWgHC8TKY) and not the fan discord or the old one that was subjected to a nazi takeover (seriously). @@ -109,12 +141,6 @@ If you're on the developer discord to talk about development, it's very difficul 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. -### I'd like to change an existing feature/npc/faction but I don't know who owns it to ask about it - -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.[^npcs] 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![^erkaside] 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. - ### How does player feedback affect the project's development? 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, and it's definitely not true; it should not be a reason to decide not to contribute.[^feedback] However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. @@ -182,6 +208,9 @@ Did you actually read all that, or just scroll down? Massive kudos if you read 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** + [^code]: 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. [^whytheory]: There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. [^bows]: 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. From 4274279509c57564cc2dc8645356c6a3037ed2bf Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 11:05:47 -0700 Subject: [PATCH 33/37] More brevity edits Down to about 6000 words now. --- doc/development_process.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index ce7bcbe95f227..d037988658df3 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -152,7 +152,7 @@ The short answer is, *yes, of course*, but this doesn't mean what some people mi 1. We are not selling a product, so we don't care about mass appeal or how many people play the game.[^massappeal] 2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think mass appeal, or what is fun, is anywhere near as obvious as it can seem at a glance. 3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. Including player-facing adjustments for every conceivable game setting is not something we want to maintain. Explaining this could be a doc in itself, but in the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's fully our intent that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage infinite preference mods. -4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. See [the section on experimental/stable](#experimentalstable). Experimental is often rendered very weird and imbalanced, sometimes for months at a time. We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. +4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. See [the section on experimental/stable](#experimentalstable). We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. 5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it.[^venera] If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also 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. @@ -167,40 +167,40 @@ This section isn't necessary to read, but contains (we hope) some useful fact-ch ### A Very Brief History of DDA -CDDA is a fork of a game called Cataclysm, developed by a guy called 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) who wanted a more gritty, realistic zombie apocalypse game made from the same general concept. Why they picked Cataclysm is anyone's guess (Kevin could probably guess, but he's not writing this document). +CDDA is a fork of a game called Cataclysm, developed by a guy called 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) who wanted 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](https://web.archive.org/web/20140211144953/http://www.jacehallshow.com/news/gaming/preview/20130626/ascii-goodness-living-breathing-3d-world-cataclysm-dark-days/) and [this one from about the same time](http://www.roguelikeradio.com/2013/07/episode-75-cataclysm-dark-days-ahead.html?m=1) show that the original developer team had much the same goals as we currently have 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 removed in a dedicated push around 2018-2020. To clear up a few common rumours that circulate in certain channels: - Kevin has always been in charge of the repo in his current capacity, even in the original oligarchy days, and there was never any sort of takeover. The other original devs just left, for various reasons. It's a hobby project, people come and go. There was no falling out or hard feelings. - Over the years we've lost a lot of developers. The reason is not as dramatic as you might think: by and large, people get bored and move on to other places. The number of major fallings-out can be counted on one hand, in over a decade of development. -- We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. Community drama followed shortly afterwards, but not for related reasons. -- That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and reddit shut down 3rd party apps. Nothing particularly exciting. +- We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. +- That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and Reddit shut down 3rd party apps. - We don't have any animosity to the other major forks of the game. Mostly, we are glad they exist, even though we know how some of them talk about us. It's our opinion that it's a *good thing* if someone who doesn't like our way of managing the project has a different place to go. We don't want to be dictators of our tiny corner of the internet, we want to make a neat game with as little drama as possible. #### Why did Kevin do this to me? -This merits its own section because it's such a frequent by-line in various Cataclysm communities. For the most part, for the last five or six years, Kevin has been fairly hands-off in the direct development of CDDA. He is quite present and involved in a lot of design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is usually started as a joke, but it obscures credit from our extremely broad base of contributors. As mentioned earlier in this document, Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides to ask nicely. If a feature was added to the game, chances are actually pretty high that someone else did it. 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, statistically it's most likely one of these people, not Kevin, changed it, and Kevin simply didn't say 'no'. +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 design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is usually started as a joke, but it obscures credit from our extremely broad base of contributors. Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides 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, not Kevin, changed it, and Kevin simply didn't say 'no'. -As a classic illustrative 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 collaborative process 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 over and over again as an example of Kevin exerting authority on the project, when his main active role was just that he didn't stop us and agreed it was our call to make as the ones doing most of the work. Similar situations have happened dozens of times, often in cases like this when it furthers a dramatic narrative to claim that it was the unilateral action of a supreme dictator. +As a classic illustrative 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 collaborative process 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 over and over again as an example of Kevin exerting authority on the project, when his main active role was just that he didn't stop us and agreed it was our call to make as the ones doing most of the work.[^controversy] Similar situations have happened dozens of times. ### Realism as a design goal -This is a much repeated buzz word. 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. This is a subtle but very important difference. Many things that would be more realistic may be nixed because of problems with play experience or play balance; for example, at time of writing, we've repeatedly shot down efforts that would make regular laundry and hygeine important, because while realistic these would be tedious and frustrating unless implemented in extremely specific ways. You can find a lot more detail about this in [the design document](https://docs.cataclysmdda.org/Lore/design-balance.html). +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.[^movies] Many things that would be more realistic may be nixed because of problems with play experience or play balance; for example, at time of writing, we've repeatedly shot down efforts that would make regular laundry and hygeine important, because while realistic these would be tedious and frustrating unless implemented in extremely specific ways. You can find a lot more detail about this in [the design document](https://docs.cataclysmdda.org/Lore/design-balance.html). -In general, the most common citation of "realism" online comes from laughable misunderstandings where glitches in experimental are mistaken for intended design in certain communities. 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 shakedown with glitches like players having to move salt in individual pinches, an obviously unintended consequence that was remedied pretty quickly. This was frequently claimed to be a "realism change", not a bug, in certain circles. While funny to think back on, this attitude has at times been actively harmful to the project, with people feeling discouraged from fixing bugs because they get the impression it's intended play. Almost universally, 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. +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 shakedown with glitches like players having to move salt in individual pinches, an obviously unintended consequence that was fixed pretty quickly. 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. ### Why did X system get worked on while the more important Y system didn't? 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 possible 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 learn how to code and to work on it yourself. Chances are this is not as difficult as it sounds. However, if you just can't do that for some reason, 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 might have a lot of sway in convincing a coder to do them a favour. +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 possible 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 learn how to code and 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. #### Why did X system get implemented with Y, but not Z? For example, why did science equipment get added but you could only loot it in one location? Why did anvils get overhauled in a way that made it hard to craft them? -This is a subset to the question above. The answer is, because the person implementing it didn't want their PR to explode into a whole bunch of extra features. This can happen for many reasons, but the most common is probably that the person implementing the PR needed that infrastructure for something else they were doing; they wanted to do it right, but they didn't want to get into the play balance of working out every other step down the road. 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: add science equipment to more spawn lists. Add some new ways to obtain anvils. 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. +This is a subset to the question above. The answer is, because 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](#How-do-I-deal-with-a-ton-of-comments-and-suggestions-to-my-idea)). 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: add science equipment to more spawn lists. Add some new ways to obtain anvils. 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. ## The Bottom Line @@ -223,3 +223,5 @@ In the end, we hope you'll share our passion for this project and decide to come [^feedback]: Also, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it however you like! [^massappeal]: 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*. [^venera]: The general design is quite flexible, and 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. +[^controversy]: 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. +[^movies]: And, 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 as simple as it seems. Hunger is a fun example of this. From 689c956adcdd050aa0f66155a86d2a8cbc96cc66 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 11:39:47 -0700 Subject: [PATCH 34/37] more brevity --- doc/development_process.md | 52 +++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index d037988658df3..476f407eeea9f 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -43,17 +43,17 @@ One of the most important concepts to understand in our project is the **experim The intention here is that if you want to *play* CDDA, you would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try to keep stable balanced and fun. -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. Because this is a volunteer-driven project, sometimes these breaks can be slow to fix. For these reasons, we don't really recommend that people play experimental as their main way to enjoy the game. Of course, many people do, and this is even important to the dev process, but from our perspective, those people are *playtesters*, not *players*. This distinction causes some confusion, so let's examine how we handle playtest feedback. -- First, we assess if the playtest feedback is valid. This is hard, and it becomes harder when news of a change is circulated to people that haven't yet tested the change.[^whytheory] -- Once we're sure the feedback is about something actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life.[^bows] -- If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but it doesn't mean we don't care, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. +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: +- First, we assess if the feedback is valid. This is hard, and it becomes harder when news of a change is circulated to people that haven't yet tested the change.[^whytheory] +- Once we're sure the concern is actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life.[^bows] +- If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but **it doesn't mean we don't care**, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. #### Why this format? **Why not finish things before putting them in a public experimental release, or revert them if they're broken?** -Various forms of this sentiment are really common, and 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 study how development works in the long term. +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, complex projects that move the game forward in leaps and bounds. If we forced ourselves to keep experimental smooth and playable all the time, contributors wouldn't be free to try new things and risk big play balance changes. Most of the complex things that make CDDA unique would have been almost impossible to create. We'd be less welcoming to new, less experienced contributors, even if we didn't want to, and 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 frustrating, partially complete state as we sort them out. If we were a professional full-time team, these things would probably progress a bit faster, but we work on volunteer time, and this is the system we've found that allows volunteers to develop systems that would be at home in a professional game, while having only a few hours a week of their time to contribute. +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. ### Mainline, in-repo mods, third party mods, and forks @@ -61,17 +61,17 @@ Cataclysm: DDA is one version of the 'Cataclysm' source code. There are many ot * **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to devs who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. * **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. -* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community: we run our fork the way we want, and we know this won't suit everyone. Having other healthy forks lets everyone develop and play, ideally without pointless drama. The most well-known fork of CDDA is Bright Nights, which is owned by a former dev of DDA with whom we are still on friendly terms. +* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community. Having other healthy forks lets everyone develop and play the way they want, ideally without pointless drama. The most well-known fork is Bright Nights, which is owned by a former dev with whom we are still on friendly terms. ### Project roles 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. Unfortunately, this can be a bit confusing. -* **CleverRaven** is the github group that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official stance in what CleverRaven does. Not all CleverRaven members are lead developers with merge permissions. However, anyone who is a member of CleverRaven has at least *some* official trust and experience with the project. +* **CleverRaven** is the github organization that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official stance in what CleverRaven does. Not all CleverRaven members are lead developers with merge permissions. However, anyone who is a member of CleverRaven has some official trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. * **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop.[^erk] Some of the senior devs have gold names on Discord, but because we love confusion, most do not. -* **Developers** are members of CleverRaven with merge permissions. These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers have green names on discord. -* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven, necessarily, but most of the time they know what they're talking about. +* **Developers** are members of CleverRaven with merge permissions, aka "mergers". These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers usually have green or gold names on Discord, although some are magenta moderators. +* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven necessarily, but most of the time they know what they're talking about. * **The dev team** is a vague term that means, roughly, "the developers and sometimes the collaborators too". * **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on Discord. * **Core contributors** is another vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot". @@ -100,7 +100,7 @@ The ultimate authority is Kevin Granade, as project lead. After him, the develo 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 that indicates a person is a member of CleverRaven with at least a little authority, like this: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) -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 trying to tell you not to take their word too seriously. +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. #### My idea was rejected, changed beyond recognition, or requires a lot more than I expected. @@ -110,7 +110,7 @@ This can happen for a few reasons. If you're not sure which applies to you, fee * Sometimes, what you want to add seems simple, but the simple solution has already been rejected because of complex flaws that will cause us problems down the road. If you're not able to do the harder work, you may have to find a different thing to work on. We won't think less of you for that, and we're sorry when this happens. * Sometimes, what you want just isn't compatible with the core game. It might go fine in a mod, and it might even [be fine to include that mod in the main repository](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/IN_REPO_MODS.md) depending on what it is. -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 definitely not more kind 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 can guarantee that nobody wants you to feel badly for having ideas and excitement about the game.[^ajoke] +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.[^ajoke] #### Do a lot of things get merged to the project, then reverted? @@ -124,7 +124,7 @@ If you're feeling overwhelmed by the amount of work being piled on you, first, w ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) A "member" badge means this person has permissions with CleverRaven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. Just as mentioned above, **this may be the result of enthusiasm**, and we might not mean that *you* have to do whatever is being suggested. Other times, it's simply that the thing you're trying to do is not going to be as easy as it looked. In that case, we'd generally prefer you to do it if you can, but it's all right to decide that we're asking for too much, and to step away from the PR. These problems can *usually* be avoided with a well-discussed Issue post or Discord conversation, but there's no way to guarantee that the right eyes are going to see your thread in time. If you're extremely averse to having this happen, the most surefire way to avoid it is to be patient 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*. Chances are whatever you want to add is just fine and you don't need to be too stressed about getting a green light. The bigger your contribution is, the more important it becomes to get clearance. +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, it's simply that the thing you're trying to do is 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, the most surefire way to avoid it is to be patient 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. #### Am I allowed to do what I want with an existing NPC/faction/feature? @@ -143,23 +143,23 @@ If someone is telling you they got banned from "devcord" for nothing at all with ### How does player feedback affect the project's development? -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, and it's definitely not true; it should not be a reason to decide not to contribute.[^feedback] However, the question of what we think of player feedback on the project side is actually pretty complex and easy to misunderstand. It's worth going into detail if you're interested. +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.[^feedback] However, the question of what we think of player feedback on the project side is actually pretty complex and worth examining in detail. #### Do we care about the players? The short answer is, *yes, of course*, but this doesn't mean what some people might think. -1. We are not selling a product, so we don't care about mass appeal or how many people play the game.[^massappeal] -2. We already know what game we want, and it's not for everyone. However, we all play this game and love it. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. We also don't think mass appeal, or what is fun, is anywhere near as obvious as it can seem at a glance. -3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. Including player-facing adjustments for every conceivable game setting is not something we want to maintain. Explaining this could be a doc in itself, but in the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's fully our intent that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage infinite preference mods. +1. We are not selling a product, so we don't care about mass appeal or how many people play the game.[^massappeal] +2. We already know what game we want, and it's not for everyone. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. +3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. In the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's intended that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage all the preference mods and switches. 4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. See [the section on experimental/stable](#experimentalstable). We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. 5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it.[^venera] If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. -We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent and uncompromised vision for the game that we follow, while also 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. +We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent vision for the game that we follow, while also 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. ##### So wait, it sounds like you're just going to do whatever you want and you don't care what the players say. -If you took that away from the above, and a few people definitely did, we'll probably never see eye-to-eye. However, we do actually care what players say. We all really do love talking to the players. It's just that this has not, and never will, manifest in us deciding to shift design goals because a bunch of people demanded it. Very often, constructive discussion with players manifests in our overall *goals* remaining the same, but us reaching a new agreement in *how to reach those goals*. Sometimes, of course, we will listen to many well-reasoned arguments, and still not change our minds. That is because 'listening' and 'caring about what you say' is not the same as 'doing what we're told'. We've learned over the years that for some, this is not 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. +If you took that away from the above, and a few people definitely did, we'll probably never see eye-to-eye. However, we do actually care what players say. Very often, constructive discussion with players manifests in our overall *goals* remaining the same, but us reaching a new agreement in *how to reach those goals*. Sometimes, of course, 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 not 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. ## Supplemental Material @@ -172,23 +172,23 @@ CDDA is a fork of a game called Cataclysm, developed by a guy called Whales. Ca 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](https://web.archive.org/web/20140211144953/http://www.jacehallshow.com/news/gaming/preview/20130626/ascii-goodness-living-breathing-3d-world-cataclysm-dark-days/) and [this one from about the same time](http://www.roguelikeradio.com/2013/07/episode-75-cataclysm-dark-days-ahead.html?m=1) show that the original developer team had much the same goals as we currently have 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 removed in a dedicated push around 2018-2020. To clear up a few common rumours that circulate in certain channels: -- Kevin has always been in charge of the repo in his current capacity, even in the original oligarchy days, and there was never any sort of takeover. The other original devs just left, for various reasons. It's a hobby project, people come and go. There was no falling out or hard feelings. +- Kevin has always been in charge of the repo in his current capacity, even in the original oligarchy days, and there was never any sort of takeover. The other original devs just left, for various reasons. There was no falling out or hard feelings. - Over the years we've lost a lot of developers. The reason is not as dramatic as you might think: by and large, people get bored and move on to other places. The number of major fallings-out can be counted on one hand, in over a decade of development. - We didn't start a developer discord because of some secret community drama. We just needed a place we could moderate for a focused discussion. -- That's also the same reason we started a developer-focused subreddit: we wanted a place where we could keep the discussion focused just on game dev and projects related to it, rather than fun and memes. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and Reddit shut down 3rd party apps. +- That's also the same reason we started a developer subreddit. It wasn't closed because of any internal strife, it was closed because we all used apps to moderate it, and Reddit shut down 3rd party apps. - We don't have any animosity to the other major forks of the game. Mostly, we are glad they exist, even though we know how some of them talk about us. It's our opinion that it's a *good thing* if someone who doesn't like our way of managing the project has a different place to go. We don't want to be dictators of our tiny corner of the internet, we want to make a neat game with as little drama as possible. #### Why did Kevin do this to me? -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 design discussions, and he has his own ongoing code projects, but for some reason he is attributed as the primary source of all changes in Cataclysm. We know this is usually started as a joke, but it obscures credit from our extremely broad base of contributors. Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise quite limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides 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, not Kevin, changed it, and Kevin simply didn't say 'no'. +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. Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides 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 illustrative 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 collaborative process 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 over and over again as an example of Kevin exerting authority on the project, when his main active role was just that he didn't stop us and agreed it was our call to make as the ones doing most of the work.[^controversy] Similar situations have happened dozens of times. +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.[^controversy] Similar situations have happened dozens of times. ### Realism as a design goal 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.[^movies] Many things that would be more realistic may be nixed because of problems with play experience or play balance; for example, at time of writing, we've repeatedly shot down efforts that would make regular laundry and hygeine important, because while realistic these would be tedious and frustrating unless implemented in extremely specific ways. You can find a lot more detail about this in [the design document](https://docs.cataclysmdda.org/Lore/design-balance.html). -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 shakedown with glitches like players having to move salt in individual pinches, an obviously unintended consequence that was fixed pretty quickly. 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. +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 shakedown with glitches like players having to move salt in individual pinches, an unintended consequence that was fixed pretty quickly. 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. ### Why did X system get worked on while the more important Y system didn't? @@ -198,9 +198,9 @@ Longer answer: Sometimes, the more important system is much harder or more intim #### Why did X system get implemented with Y, but not Z? -For example, why did science equipment get added but you could only loot it in one location? Why did anvils get overhauled in a way that made it hard to craft them? +For example, why did science equipment get added but you could only loot it in one location? -This is a subset to the question above. The answer is, because 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](#How-do-I-deal-with-a-ton-of-comments-and-suggestions-to-my-idea)). 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: add science equipment to more spawn lists. Add some new ways to obtain anvils. 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. +This is a subset to the question above. The answer is, because 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](#How-do-I-deal-with-a-ton-of-comments-and-suggestions-to-my-idea)). 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: 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. ## The Bottom Line From fc86a5bacbe01392941c0682768216bf1ecab721 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 12:03:33 -0700 Subject: [PATCH 35/37] Final? brevity pass --- doc/development_process.md | 59 +++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 476f407eeea9f..58b5dadf61c16 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -2,9 +2,9 @@ **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, as individuals are welcome to disagree with the team stance. +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](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html), which talks about some of the common ideas we hear for the project and offers reasons about why they might not have been added yet. [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. +This document assumes you have a basic understanding how GitHub works. Please see the [guide for new contributors](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html). [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. ## Table of Contents @@ -33,7 +33,7 @@ This document assumes you have a basic understanding how GitHub works. Please s ## The basic concept -At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). The project is led by Kevin Granade, who owns the CleverRaven group that runs this branch 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[^code]. +At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). 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.[^code] ## The structure of the project @@ -41,11 +41,11 @@ At its core, CDDA is a survival simulation game. [The design doc outlines what 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 would play on stable. This is a carefully curated snapshot of the game with as few major bugs and balance issues as we can manage. We don't consider stable *perfect*; sometimes, features have to ship in states we consider unfinished, because of the volunteer nature of the game. However, we try to keep stable balanced and fun. +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.[^fun] 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: - First, we assess if the feedback is valid. This is hard, and it becomes harder when news of a change is circulated to people that haven't yet tested the change.[^whytheory] -- Once we're sure the concern is actually happening, we check if it's intended behaviour or not. If not, we start looking for solutions. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life.[^bows] +- Once we're sure the concern is actually happening, we check if it's intended behaviour or not. If it's an outright bug, we try to fix it. If it's an unintended consequence of complex systems interacting, often the solution is to think about how the mechanic should work in real life.[^bows] - If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but **it doesn't mean we don't care**, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. #### Why this format? @@ -59,9 +59,9 @@ Allowing things to get broken in experimental allows us to have big, ambitious p 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". -* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include. This is the result of having had a few dozen increasingly abandoned mods whose maintenance was up to devs who did not use those mods. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. -* **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because for various reasons their owners haven't decided to add them. These mods aren't lesser, they're just not our responsibility. We don't generally offer bugfixing on them simply because we don't know what they are and what they do. -* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community. Having other healthy forks lets everyone develop and play the way they want, ideally without pointless drama. The most well-known fork is Bright Nights, which is owned by a former dev with whom we are still on friendly terms. +* **In-repo mods** are mods that we distribute with the game. [We have a fairly specific set of criteria](https://docs.cataclysmdda.org/IN_REPO_MODS.html) for what mods we'll include. If you have a mod you are comfortable releasing under CC-BY-SA and want to include it, and it meets these criteria, you'd probably be fine to include it in mainline and we'd probably love to have it. +* **Third party mods** are mods that aren't in the main repository, either because they don't meet the criteria, or because their owners just haven't decided to add them. These mods aren't lesser, they're just not our responsibility. +* **Forks** are other versions of the Cataclysm source code, run by different people, presumably with different design goals. We consider forks an important part of a healthy open-source community. Having healthy forks lets everyone develop and play the way they want, ideally without pointless drama. The most well-known fork is Bright Nights, which is owned by a former dev with whom we are still on friendly terms. ### Project roles @@ -88,9 +88,9 @@ This is built from concerns we've heard from other new contributors to the proje ### How can I make sure my contribution will be accepted? -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](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel, or post in [the discourse forum](https://discourse.cataclysmdda.org/)[^discourse] 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 to the project. +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](https://discord.gg/hqWgHC8TKY) in the Development or CDDA-Discussion channel, or post in [the discourse forum](https://discourse.cataclysmdda.org/)[^discourse] 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. -By and large, 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 basically 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 project like this. +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. @@ -98,7 +98,7 @@ If you've created an issue or a discourse post and aren't getting much feedback, 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 that indicates a person is a member of CleverRaven with at least a little authority, like this: +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: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) 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. @@ -120,11 +120,11 @@ The best way to protect yourself from getting something reverted, or rejected be #### How do I deal with a ton of comments and suggestions to my idea? -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 with CleverRaven. On GitHub, it can be tougher to tell who's in charge; this is just a fundamental flaw with how the site works, and there's no easy way around it. We're doing our best to make sure that more senior project members get a user badge, like this: +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: ![image](https://github.com/I-am-Erk/Cataclysm-DDA/assets/45136638/6106b80f-274e-43c7-a937-58f601f035e6) -A "member" badge means this person has permissions with CleverRaven and so has a pretty high chance of being correct, but remember that if they say they're not an authority in this area, that means you shouldn't overvalue them either. A "contributor" badge means they've worked with the project before, but don't have any official authority. 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. +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, it's simply that the thing you're trying to do is 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, the most surefire way to avoid it is to be patient 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. +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. #### Am I allowed to do what I want with an existing NPC/faction/feature? @@ -137,29 +137,29 @@ As a general rule, in fact, we would prefer it if new contributors would feel we We don't think so, but obviously we're biased. First, make sure you're looking at [the developer discord](https://discord.gg/hqWgHC8TKY) 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 first[^spam]. If you're worried about getting in trouble for your memes or fun chat times, we suggest just going to [the community discord](https://discord.gg/byxwnAU -), 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 not the place to go for memes about cargo socks. It *is* the place to go to see the devs talking like normal people instead of giving dry technical responses on GH. +), 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. ### How does player feedback affect the project's development? -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.[^feedback] However, the question of what we think of player feedback on the project side is actually pretty complex and worth examining in detail. +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.[^feedback] However, the question of what we think of player feedback on the project side is actually complex and worth examining in detail. #### Do we care about the players? The short answer is, *yes, of course*, but this doesn't mean what some people might think. 1. We are not selling a product, so we don't care about mass appeal or how many people play the game.[^massappeal] -2. We already know what game we want, and it's not for everyone. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any player feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal. See number 1. -3. This game is one of the most adjustable and moddable games out there, but that's an outcome of good data driven design, not a specific goal we have. In the end, it comes down to number 2 plus a bunch of details on the nitty-gritty of managing the code and play balance. It's intended that if you want something to run differently, you can mod it out; we just don't want to be on the hook to bugtest and manage all the preference mods and switches. -4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. See [the section on experimental/stable](#experimentalstable). We will basically never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. -5. The project isn't a democracy. This rubs some folks the wrong way, but it just isn't. However, the project also isn't a dictatorship, it's more like an open forum with a moderator. If you have opinions about something, make your case for it.[^venera] If what you want doesn't conflict with the game design, and you make a good case for it, you can very often change our minds. +2. We already know what game we want, and it's not for everyone. Nothing we add ever has the goal of making a game we wouldn't like to play ourselves. Any feedback that amounts to "change this aspect of the game that *you* like into something *I* prefer" is just a non-starter. We know that sometimes what you prefer has more mass appeal (see number 1) and we're sure it's more fun *for you*. +3. This game is one of the most moddable games out there, but that's an outcome of data-driven design, not a specific goal we have. In the end, it comes down to number 2 plus a bunch of details about managing the code and play balance. It's intended that if you want something to run differently, you can mod it out; we just don't want to be on the hook to maintain all the preference mods and switches. We tried it and it sucked. +4. Many times, player feedback concerns come down to the playability of the experimental branch of the game. See [the section on experimental/stable](#experimentalstable). We almost never revert changes to experimental that we've added in order to test them, nor are we likely to relegate those changes to a mod or an option, because this interferes with testing. See 2 and 3. However, nearly all the time, whatever is bothering players about current experimental is something that will shake out and become sorted in time. +5. The project isn't a democracy. However, the project also isn't a dictatorship: it's more like an open forum with a moderator. If you have opinions about something, make your case for it.[^venera] If what you want doesn't conflict with the game design, you can very often change our minds. -We feel pretty strongly that the reason this project has thrived for so long is that we have a consistent vision for the game that we follow, while also 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. +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. ##### So wait, it sounds like you're just going to do whatever you want and you don't care what the players say. -If you took that away from the above, and a few people definitely did, we'll probably never see eye-to-eye. However, we do actually care what players say. Very often, constructive discussion with players manifests in our overall *goals* remaining the same, but us reaching a new agreement in *how to reach those goals*. Sometimes, of course, 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 not 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. +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. ## Supplemental Material @@ -167,9 +167,9 @@ This section isn't necessary to read, but contains (we hope) some useful fact-ch ### A Very Brief History of DDA -CDDA is a fork of a game called Cataclysm, developed by a guy called 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) who wanted a more gritty, realistic zombie apocalypse game made from the same general concept. +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](https://web.archive.org/web/20140211144953/http://www.jacehallshow.com/news/gaming/preview/20130626/ascii-goodness-living-breathing-3d-world-cataclysm-dark-days/) and [this one from about the same time](http://www.roguelikeradio.com/2013/07/episode-75-cataclysm-dark-days-ahead.html?m=1) show that the original developer team had much the same goals as we currently have 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 removed in a dedicated push around 2018-2020. +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](https://web.archive.org/web/20140211144953/http://www.jacehallshow.com/news/gaming/preview/20130626/ascii-goodness-living-breathing-3d-world-cataclysm-dark-days/) and [this one from about the same time](http://www.roguelikeradio.com/2013/07/episode-75-cataclysm-dark-days-ahead.html?m=1) 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: - Kevin has always been in charge of the repo in his current capacity, even in the original oligarchy days, and there was never any sort of takeover. The other original devs just left, for various reasons. There was no falling out or hard feelings. @@ -180,27 +180,27 @@ To clear up a few common rumours that circulate in certain channels: #### Why did Kevin do this to me? -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. Kevin is the *final voice* in what goes in to the project or does not. However, his powers are otherwise limited. In particular, it's helpful to understand that neither the devs, nor Kevin, have any "additive" influence. Unless we put something in ourselves, we have no way to influence other people to add it besides 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'. +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.[^controversy] Similar situations have happened dozens of times. ### Realism as a design goal -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.[^movies] Many things that would be more realistic may be nixed because of problems with play experience or play balance; for example, at time of writing, we've repeatedly shot down efforts that would make regular laundry and hygeine important, because while realistic these would be tedious and frustrating unless implemented in extremely specific ways. You can find a lot more detail about this in [the design document](https://docs.cataclysmdda.org/Lore/design-balance.html). +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.[^movies] 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](https://docs.cataclysmdda.org/Lore/design-balance.html). -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 shakedown with glitches like players having to move salt in individual pinches, an unintended consequence that was fixed pretty quickly. 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. +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. ### Why did X system get worked on while the more important Y system didn't? 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 possible 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 learn how to code and 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. +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. #### Why did X system get implemented with Y, but not Z? For example, why did science equipment get added but you could only loot it in one location? -This is a subset to the question above. The answer is, because 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](#How-do-I-deal-with-a-ton-of-comments-and-suggestions-to-my-idea)). 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: 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. +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](#How-do-I-deal-with-a-ton-of-comments-and-suggestions-to-my-idea)). 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. ## The Bottom Line @@ -212,6 +212,7 @@ In the end, we hope you'll share our passion for this project and decide to come **Footnotes** [^code]: 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. +[^fun]: At least by certain definitions of fun, which may or may not involve being eaten by a mi-go. [^whytheory]: There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. [^bows]: 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. [^erk]: This happened to I-am-Erk somehow and he's still not sure why he hasn't run away screaming. From 74580e03049105f5305324b7412e0cc19674490f Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 12:18:44 -0700 Subject: [PATCH 36/37] Update development_process.md --- doc/development_process.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 58b5dadf61c16..99549d4b92174 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -4,7 +4,7 @@ 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](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](https://docs.cataclysmdda.org/FREQUENTLY_MADE_SUGGESTIONS.html). [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the basic structure of any open source project. +This document assumes you have a basic understanding how GitHub works. Please see the [guide for new contributors](https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors) for more info there. You might also find helpful information in the [Frequently Made Suggestions doc](FREQUENTLY_MADE_SUGGESTIONS.md). [This guide from GitHub](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) also gives a decent run-down of the structure of any open source project. ## Table of Contents @@ -33,7 +33,7 @@ This document assumes you have a basic understanding how GitHub works. Please s ## The basic concept -At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](https://docs.cataclysmdda.org/Lore/design-doc.html). 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.[^code] +At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](./Lore/design-doc.md). 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.[^code] The rest of the project's structure is organized chaos, and understanding it is daunting at first. ## The structure of the project @@ -116,7 +116,7 @@ An issue we run into occasionally is that our responses can be short and straigh 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]([https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/reviewing_PR_guide.md](https://docs.cataclysmdda.org/reviewing_PR_guide.html)), 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. +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](reviewing_PR_guide.md)), 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. #### How do I deal with a ton of comments and suggestions to my idea? @@ -130,7 +130,7 @@ If the requested changes are coming from a trusted source, and it's more than yo 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.[^npcs] 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![^erkaside] 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. +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. ### Is the Discord strict? @@ -186,7 +186,7 @@ As a classic example, when we first added the mod inclusion criteria and set a b ### Realism as a design goal -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.[^movies] 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](https://docs.cataclysmdda.org/Lore/design-balance.html). +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.[^movies] 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](./Lore/design-balance.md). 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. @@ -213,16 +213,15 @@ In the end, we hope you'll share our passion for this project and decide to come [^code]: 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. [^fun]: At least by certain definitions of fun, which may or may not involve being eaten by a mi-go. -[^whytheory]: There's a tendency for theory crafting to be louder than playtests, and we've had some pretty severe lost work hours when devs have tried to solve a problem that turned out to not actually be happening in game. +[^whytheory]: 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. [^bows]: 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. [^erk]: This happened to I-am-Erk somehow and he's still not sure why he hasn't run away screaming. [^discourse]: 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. [^ajoke]: 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. [^spam]: Unless you're a spambot, but then how are you reading this? [^npcs]: 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. -[^erkaside]: I'm going to break the "dev team" voice for this section and start speaking as Erk, one of the people who has added a ton of NPCs and dialogue to the game, because I think it's the most illustrative way to explain. This is a thing I personally struggle with sometimes, because all my NPCs are my babies, but ultimately even as a senior developer, I understand and *expect* them to be changed without consulting me. If someone were to go in and give Dino Dave or Rubik a bunch of dialogue that strays wildly from the characters I've developed in my head, *I do not consider myself any more of a final authority than this new contributor is*, except in the sense that I know all their existing dialogue very well. I might offer some feedback on voice, but unless it conflicts with the way they've been presented in-game, I don't consider it any kind of faux pas to change them drastically from what I imagine. This is, in my opinion, how we should think of all NPCs, or factions, or maps, etc. Once they're in the game, they're free to be taken in new and unexpected directions. Really, that's the beauty of an open source collaborative project like this. The only exception is when it impacts long-term planning for the game. Note that this isn't how all contributors feel about their NPCs and that's another reason it's a good idea to check in first. [^feedback]: Also, if *you* want to listen to player feedback on your additions to the game, you're welcome to do it however you like! [^massappeal]: 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*. -[^venera]: The general design is quite flexible, and 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. +[^venera]: 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. [^controversy]: 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. -[^movies]: And, 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 as simple as it seems. Hunger is a fun example of this. +[^movies]: 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. From 7776849e0a455813a63e14301d2ae9300d8afae8 Mon Sep 17 00:00:00 2001 From: I-am-Erk <45136638+I-am-Erk@users.noreply.github.com> Date: Fri, 24 May 2024 12:37:49 -0700 Subject: [PATCH 37/37] minor structure adjustments --- doc/development_process.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/doc/development_process.md b/doc/development_process.md index 99549d4b92174..150b3f6274a22 100644 --- a/doc/development_process.md +++ b/doc/development_process.md @@ -8,8 +8,7 @@ This document assumes you have a basic understanding how GitHub works. Please s ## Table of Contents -* [The basic concept](#The-basic-concept) -* [The structure of the project](#The-structure-of-the-project) +* [The basic structure](#The-basic-structure) * * [Experimental/Stable](#experimentalstable) * * * [Why this format?](#Why-this-format) * * [Mainline, in-repo mods, third party mods, and forks](#mainline-in-repo-mods-third-party-mods-and-forks) @@ -35,8 +34,6 @@ This document assumes you have a basic understanding how GitHub works. Please s At its core, CDDA is a survival simulation game. [The design doc outlines what we mean by this](./Lore/design-doc.md). 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.[^code] The rest of the project's structure is organized chaos, and understanding it is daunting at first. -## The structure of the project - ### Experimental/Stable One of the most important concepts to understand in our project is the **experimental/stable branch** system. @@ -49,7 +46,7 @@ On the other hand, in the experimental branch, we allow things to get broken. W - If the behaviour is intended, we consider why people are frustrated by it. Is player-end feedback a problem? Is the UI creating tedium? This is an area where things can languish for a while, but **it doesn't mean we don't care**, it's just that these problems are hard to fix, and often take different skills than the original addition. This is also where the experimental/stable thing becomes relevant. For example, on a few occasions, we've patched the behaviour out and then put it back in after stable. This is to preserve gameplay for the people playing the curated, stable version of the game, while also continuing to work on the features we want to include. #### Why this format? -**Why not finish things before putting them in a public experimental release, or revert them if they're broken?** +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. @@ -65,13 +62,13 @@ Cataclysm: DDA is one version of the 'Cataclysm' source code. There are many ot ### Project roles -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. Unfortunately, this can be a bit confusing. +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. -* **CleverRaven** is the github organization that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official stance in what CleverRaven does. Not all CleverRaven members are lead developers with merge permissions. However, anyone who is a member of CleverRaven has some official trust and experience with the project. +* **CleverRaven** is the github organization that owns this fork of CDDA. That might sound precise, but it's actually a little hard to define who is or is not part of CleverRaven and whether or not they have any official authority. Not all CleverRaven members are lead developers with merge permissions, but anyone who is a member of CleverRaven has some trust and experience with the project. * The **Project Lead** is Kevin Granade. He mainly serves as the final voice in what can go into the project, and arbitrates disputes between other members of the team. * **Senior developers** have merge permissions with CleverRaven and have been around a long time. This is a very fuzzy role, none of us know exactly what makes a person a "senior" developer versus any other kind of "developer". It just kind of happens, usually because they're doing leadership things and not being told to stop.[^erk] Some of the senior devs have gold names on Discord, but because we love confusion, most do not. -* **Developers** are members of CleverRaven with merge permissions, aka "mergers". These folks are trusted enough to be allowed the very dangerous ability to merge to the main project line. They are the main workforce of the game's management team. Developers usually have green or gold names on Discord, although some are magenta moderators. -* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven necessarily, but most of the time they know what they're talking about. +* **Developers** are members of CleverRaven with merge permissions, aka "mergers". These folks are trusted enough to be allowed to merge to the main project branch. They are the main workforce of the game's management team. Developers usually have green or gold names on Discord. +* **Collaborators** are contributors that have been around a while, and shown that they "get" the direction of the project. We mark their names blue on Discord to indicate this; the purpose of the role is to help newer users to identify if the feedback they're getting is from a fellow new person, or from someone with a bit more experience. Collaborators don't speak for CleverRaven necessarily, but most of the time they know what they're talking about. * **The dev team** is a vague term that means, roughly, "the developers and sometimes the collaborators too". * **Contributors** are people who have added something to the game, anything. Code, art, translations, writing, are all included. While this is the most numerous group, we also think it's the most important one. Everyone from Kevin onward is a contributor. Contributors have purple names on Discord. * **Core contributors** is another vague term that we use sometimes, meaning "the developers, the collaborators, and a bunch of the contributors that have been around a lot".