Clarify mod policy, guidelines and guides

[Photoloss]

The newcomers' guide explicitly calls to "modders" and even the "mod or mainline" section does not distinguish between mods shipped with the main releases and unaffiliated third-party mods.

• There is no mention of a preferred third-party mod repository or lack thereof.
• There are no contribution standards listed for integrated mods despite these clearly being different from the base game.
• The guide segues into instructions for filing a pull request. While titled "mainline" this section continues to use terms such as "modder" so one could easily assume the procedure for "actual mods" to be similar.
• The presence of other content mods combined with the language of the guide could be misunderstood to imply all third-party mods should be submitted as main repo additions. I know this to not be the case but the guide is directed at complete newcomers who might not even be aware of any third-party mods existing while they do see Salvaged Robots listed on world creation.
• Contrary to what one might expect given other /doc entries such as GAME_BALANCE.md or NPCs.md the MODDING.md contains neither guidelines nor technical information (e.g. modinfo.json documentation) on actual mods.

[Night-Pryanik]

Good issue. This should've be brought upfront years ago.

[mlangsdorf]

Please submit some preferred text and I'll add it to the guide.

[Photoloss]

@mlangsdorf as a PR or is there a different format? (not seeing an "edit" button on that wiki page)

Points 2 and 4 require input from project managers, ideally both an overall stance/vision and concrete actionable points where present (for example the github ToS ban raunchy stuff but I have no idea whether PG-13 romance is absent purely for technical reasons/lack of interest or active opposition, nor why dinosaurs are included while PK's, Cata++ and so on aren't)

Point 5 is beyond my knowledge, for example I assumed some kind of author or maintainer entry was considered necessary for main repo mods but was told this is not the case.

[mlangsdorf]

Let's discuss and refine it here in this issue. The wiki doesn't go through the PR process for good reasons.

[Photoloss]

Regarding the wiki page specifically:

• Change the name and all references to it to "...first time contributors", most importantly the page title and the link on the wiki home page
• In the mod or mainline section clarify there are in fact three options for content additions, e.g.

When you have an idea for new content, you have three options for introducing it to the game: you can add it to the mainline content in data/json , as an optional mod in data/mods/ or distribute it independently if necessary. These guides assume that you are going to add mainline content, because that's what you probably should do.

• Add a section detailing the differences between main repo mods and third-party ones, and ideally introduce official terms. "mainline mods"/"official mods" versus "third-party mods"/"unofficial mods" maybe. Clarify that the former are hosted here and vetted to certain standards (ideally link to said standards) while the latter are not supported by the main project.

• Update the terminology in the "Why not a mod?" section depending on what the actual stance on main repo mods is. Based on @Night-Pryanik's opinion I assume not everyone would actually want the "Cataclysm: Enemy Unknown" total conversion to be submitted to this repo as it would likely dwarf all current content mods by an order of magnitude.

• In the merging into mainline section, point 8 change "modder" to "contributor". Or even "Contributor" (capital C) to mirror the tag applied in the github interface.

• Potentially add a point explaining the github "Member" status, in particular that they are senior devs who manage the project, assist with the tests in point 5 and also a nicer way of saying "these are the bosses, listen and obey" (I am not good with that type of language)

• Add a new page echoing the sentiments voiced here or whatever the official equivalent is. Append a link to this "beyond JSON" page to the end of the beginner's guide as well as the Miscellaneous page.

Mod terminology could stand to be clarified on the FMS page as well. For example "Magic powers: mod only" implies the Arcana mod would be accepted into the main repo especially since the next point on bodily functions is not enforceable on independent third parties. Instead of copy-pasting a stock "we’d be happy to have support for it in the code" message you could also link to the "beyond JSON" statement once it actually exists

Speaking of which, add the following to the FMS, based on Kevin's comments here and here:

Using zombie parts: ["official mod only" or "mostly no"]

All supernatural properties, abilities and other aspects of zombies rapidly dissipate upon "death" except for a lingering tainted presence.

From a game balance perspective zombies are very abundant and should only be used under limited lore-friendly circumstances in consumables, trivial early items or with lasting risks and drawbacks.

Exact wording obviously subject to correction by Kevin or other authorities as I am merely paraphrasing him. The "tainted presence" and "consumables" aspects cover mutagen, tainted bone can be used in place of regular bone in simple recipes like the bone needle and the "lasting risks" part covers zlaves and the general "shocker battery" concept which I have seen supported by some key contributors and never explicitly refused.

[kevingranade]

Disclaimer we can possibly shim into contribution guidelines somewhere:

There is a great deal of uncertainty intrinsic in game development, especially in a wide-open sandbox game. As such each contributor is responsible for understanding the tone and lore of the game and attempting to match their contributions to it. Maintainers and contributors work together to make this as easy as possible, but we cannot specify every detail, and we cannot answer every question.

Maintainers may not have time to provide feedback you are happy with. Please accept feedback in good faith and address it rather than arguing its validity. Also keep in mind that when you are asking for clarification or guidelines, that is a request, no one is obligated to answer.

[Photoloss]

There is a great deal of uncertainty intrinsic in game development

Also keep in mind that when you are asking for clarification or guidelines, that is a request, no one is obligated to answer.

This reads overly negative compared to the more motivating tone of the guide e.g.

JSON looks complicated and intimidating when you first start, but it is just text.

But CDDA is open source, and welcomes contribution.

please add a mission chain like this!

I may have made the process of submitting a PR sound difficult, but the CDDA community is friendly and welcoming to new content.

Be patient, ask for advice, and soon you'll have a "Great contributor" tag after your name on Discourse.

Meanwhile the entry actually called "contributor guidelines" is entirely technical right now so it doesn't really fit there either.

Maybe it could be rephrased into an "introduction"/"overview" on the wiki home page?

Cataclysm: Dark Days Ahead is a wide-open sandbox game developed as an open source project. As such we have no all-encompassing content direction and no rigid guidelines, but we do expect every community member to act maturely and to the overall benefit of the project. Thus each contributor is responsible for understanding the tone and lore of the game and attempting to match their contributions to it. Maintainers and contributors work together to make this as easy as possible but we cannot specify every detail and we cannot answer every question.

Maintainers may not have time to provide extensive feedback to your full satisfaction. Please accept feedback in good faith and address it rather than arguing its validity or minute details. Also keep in mind that no one is obligated to answer you, asking anything of the maintainers is a request.

If you would like to engage in more elaborate discussions, collect feedback from the general community, learn more about the game lore or develop your ideas into fully-fledged projects please visit the [Official Forum] (Discourse link) <or other community outlets on [Discord], [IRC] and [reddit]>

That last bit obviously only including ones the repo is willing to associate with, reddit has a (sometimes undeserved) reputation for toxicity and I'm not familiar with the other two. Yes I know there already is a forum link in the sidebar but in my experience elsewhere you could make the game launch through the forum and most would still be happily oblivious to its existence.

(and no the irony of me writing this is not lost on me :laughing: )

[kevingranade]

Change the name and all references to it to "...first time contributors"

Why? I'm extremely skeptical that there is any actual confusion here.

or distribute it independently if necessary. differences between main repo mods and third-party ones

If you don't want to add your content to the main project, then the main project has nothing to say about your content. It makes no sense for us to have a "policy" or "guidelines" about such content.

Update the terminology in the "Why not a mod?" section depending on what the actual stance on main repo mods is.

It's roughly accurate, if you think it can be improved please suggest something.

"Magic powers: mod only" implies the Arcana mod would be accepted into the main repo

It would be, the decision to have Arcana outside the repo has nothing to do with the subject matter of the mod.

Mod terminology could stand to be clarified on the FMS page as well.

I'm not interested in feedback on the FMS page.

That leaves three suggestions: The Modder -> Contributor change, which needs a stronger rationale. A request to clarify the status of maintainers, which needs verbiage. A request for a formal statement outlining when we will accept c++ code changes that support external mods, which needs verbiage.

As Mark said, "Please submit some preferred text".

If you don't think you can draft said text since it concerns policy positions, then we just need to close this issue and you can wait for someone to get around to it.

[Photoloss]

The Modder -> Contributor change, which needs a stronger rationale.

Most "modding" communities are organised by third parties, often with no oversight or support from the developers themselves. Quality standards are usually enforced via ratings and word of mouth rather than mandatory curation. I agree there should be no confusion when you sit back, read everything and think, this is mainly intended to invoke a different tone on first impression.

It's roughly accurate, if you think it can be improved please suggest something.

Rephrase the "mod or mainline" section:

When you have an idea for new content, you have three options for introducing it to the game: you can add it to the mainline content in data/json , as an optional mod in data/mods/ or distribute it independently if necessary. These guides assume that you are going to add mainline content, because that's what you probably should do.

Why not a mod?

Adding content through third-party mods makes a lot of sense when dealing with a commercial, closed source, game. But CDDA is open source, and welcomes contribution. Content that's in a mod gets updated haphazardly at best, and sometimes mods get broken when the mainline game changes underneath them. Content that is in mainline is much more likely to get updated when the game changes. The mods supplied directly with the game itself are kept functional where possible but still do not enjoy the same attention as the mainline, both from players and from developers.

You should add new content to a mod if, and only if, your new content wouldn't be the kind of thing that most players would want to see. If you want to add a new mission chain where the Old Guard rep sends you out to assassinate rival faction leaders (please add a mission chain like this!), that should be in mainline. If you want to add a total overhaul of the game around an alien invasion called Cataclysm: Enemy Unknown (please add a total overhaul of the game like this!), that content should be in a mod. As these examples should illustrate mods also are not subject to the same level of scrutiny in regards to realism, lore consistency and balance as the mainline game provided they can make up for it with engaging gameplay.

In general, there's very few good reasons to add content via a mod and lots of reasons not to. In particular we do not have ties with nor directly support third-party distributors, if a mod is not part of this repository someone else carries the full responsibility and we cannot maintain/fix it.

fin. ==========================================================

A request to clarify the status of maintainers, which needs verbiage.

Appended after "merging into mainline" section for example:

Repository Maintainers

A select few veteran contributors act as Maintainers of the repository, denoted by the Member tag next to their name. They are our closest equivalent to "development leads" and "administrators" handling the technical side of adding your changes to the game and curating the overall quality of content. If a Maintainer/Member replies to highlight technical issues with your submission or requests changes pay extra close attention as these concerns are very likely blocking it from being included.

Please respect that the Maintainers oversee all contributions so they will not always have the time to reply in full detail or provide step-by-step instructions. If a Maintainer offers contact information or private communication they do so out of their own desire to help.

========================================================== And for C++ additions:

More than JSON

So you wanted to add something but discovered JSON editing alone was not able to do so? No fear, we also accept changes to the game's core C++ code through the same process! For this you need to know C++ programming which unfortunately we cannot provide a simple introduction to, so please join the community in the forum or discord to get yourself set up.

A key difference to JSON editing is that you need to [compile] (https://github.com/CleverRaven/Cataclysm-DDA/blob/master/COMPILING.md) C++ code before your changes take effect. For this reason third-party mods cannot change the C++ source of the released game itself but we DO accept code changes necessary for mods to work. Ideally such additions should be relevant to the base game to ensure the code is kept up-to-date with other mainline changes. If this is not the case (let's say you added a functioning jetpack which was deemed "too unrealistic") you should add comments to your code explaining a mod relies on them so no one will break your work by accident.

As C++ additions can affect the performance of the core game to a much greater degree you should work on simpler JSON contributions first until you are more familiar with our review procedure. Keep contributing and learning and soon enough your shiny new code will be running in the latest release!

I am sure @mlangsdorf can improve the phrasing a lot. Going slightly off topic the "merged in mainline" section is a masterpiece strictly laying down the rules but not overstepping into condescension or absolutism. There's always a way out or an offer for help, excellent job! :+1:

[mlangsdorf]

Pages updated. Please review.

Specific changes:

• It's now the "Guide to adding new content to CDDA for first time contributors" because that is a more sensible name. Thanks for the suggestion.
• https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-contributors expanded to include default content, CleverRaven mods, and 3rd party mods. Also the contributor, developer, maintainer, Kevin hierarchy with some tips for dealing with Kevin.
• short section on C++ contribution added https://github.com/CleverRaven/Cataclysm-DDA/wiki/Guide-to-adding-new-content-to-CDDA-for-first-time-modders:-C++-Code

[AMurkin]

Please also update the link text on the main wiki page.

[DracoGriffin]

Please also update the link text on the main wiki page.

Fixed.

[Photoloss]

Looking excellent to me! :+1:

The link to the FMS page under the CleverRaven or 3rd Party? section does not line up perfectly with its current content but definitely gets the point across, and I hope anyone who makes it that far down will also think about what they read.

I hope you got approval from Kevin for that one paragraph, not for the actual content just the "explicitly naming a person in a beginner's guide" angle. Granted he is the project lead but I don't want him to suffer personal harassment.

[mlangsdorf]

Yeah, I cleared it with him. Thanks.

Closing the issue as it seems to be resolved.