Documentation Overhaul

[lhearachel]

This is a bit of a kitchen-sink issue so that we don't lose track of ideas for easy-win improvements to documentation and process. In particular, our top-level documentation -- INSTALL.md and CONTRIBUTING.md -- have gone without touch-ups for some time and could do with some attention to standardize their language and structure and harden them against potential misreadings.

Some additional thoughts:

1. Should we centralize these documents in the existing docs folder, or does that make them less visible? Are they visible as-is among the sea of other files in the repository root?
2. Should we adopt a Code of Conduct?
3. Is a license file in-scope? The typical ones are likely very out of the picture, given the nature of this work. We may want to discuss this with the pret mods.
4. Is a citation file in-scope?
5. Should we adopt a Pull Request template to standardize some basic pre-PR procedures? I am thinking:
   1. A space to list key files and functions.
   2. A space to raise any concerns that the author has with the PR before a reviewer comes to it.
   3. A space to pre-document some systems that may be initially confusing.
   4. A check-list of expected pre-actions (e.g., make format).
   5. A free-form space for any other pre-review notes.

[CharlesFolz4]

For point 1, INSTALL.md is already linked in the README.md, that makes it very visible from a standard starting point without any searching needed. However, CONTRIBUTING.md isn't linked anywhere that I could find, and it would make it more discoverable if it were linked from one of the other two documents. That way, everything required to get started would be encountered just by reading the README, which I think is a reasonable expectation.

I also think that it may be beneficial for new contributors to have a list of basic information that is generally useful to know, such as a link to the overlay ID mappings. If it's useful enough and non-obvious enough to have documentation outside of the code, it's probably also useful and non-obvious enough to have that documentation be as easily discoverable as possible.

[lhearachel]

I also think that it may be beneficial for new contributors to have a list of basic information that is generally useful to know, such as a link to the overlay ID mappings. If it's useful enough and non-obvious enough to have documentation outside of the code, it's probably also useful and non-obvious enough to have that documentation be as easily discoverable as possible.

I definitely think that a miniature "contributor wiki" could be nice to have, if only to keep as an internal source of information for ourselves. I'm eyeing some higher-scope documentation along the lines of describing how the game's internals work for some of that sort of knowledge, but there are some other aspects worth looking at, too, such as:

1. Guidelines for where unpacked data files should be stored and how they should be re-packed into the game
2. How to translate raw graphics into modifiable formats (including a nitrogfx how-to for common options)
3. How to navigate the build system (maybe just a Meson crash-course?)

[Kuruyia]

My two cents:

1. Should we centralize these documents in the existing docs folder, or does that make them less visible? Are they visible as-is among the sea of other files in the repository root?

Completely agreeing with what's been brought up by @CharlesFolz4 on that point.

As for the location of INSTALL.md and CONTRIBUTING.md, I think that either you know those files exist, in which case you can easily access them from the repository root, or you don't know they exist, in which case the README needs to give you a nudge in their direction.

3. Is a license file in-scope? The typical ones are likely very out of the picture, given the nature of this work. We may want to discuss this with the pret mods.

I am not a lawyer, but it seems to me that this repo is already, at best, in a legal gray area. So I don't think a license would have legal value.

2. Should we adopt a Code of Conduct?

5. Should we adopt a Pull Request template to standardize some basic pre-PR procedures?

Those ones I think are interesting. They are the kind of things that, imo, should be standardized across pret repositories (by using the .github repository for instance), because it'd be a bit weird to have (intentionally exaggerating) two completely different code of conducts under the same org. So maybe it's worth to talk about that to the maintainers of the other repos/pret mods as well?

For the code of conduct, it could be shared across repos without any change required. I could be wrong, but I think that the points you mentioned about the PR template applies to the majority of the other repos as well, so this could be shared as well.

Throwing the question here, would an issue template be good as well?

Also, about check-lists in PR templates, I find them annoying. They are just things you'll have to check each time you open a PR, even though you already know what to check by your second PR. (yes, this is a very minor inconvenience and I'm being petty about it)
Staying on the topic of code formatting verification, I think the better experience is to have a CI that checks that (we already have) and, if it doesn't pass, a bot could comment on the PR with what failed, why it failed, and how to fix it. Potentially only commenting for first-time contributions. Potentially deleting its comment after the issue is fixed to avoid polluting the comment feed.

[lhearachel]

As for the location of INSTALL.md and CONTRIBUTING.md, I think that either you know those files exist, in which case you can easily access them from the repository root, or you don't know they exist, in which case the README needs to give you a nudge in their direction.

Understandable. That makes sense to me.

Those ones I think are interesting. They are the kind of things that, imo, should be standardized across pret repositories (by using the .github repository for instance), because it'd be a bit weird to have (intentionally exaggerating) two completely different code of conducts under the same org. So maybe it's worth to talk about that to the maintainers of the other repos/pret mods as well?

I agree, but I also think that the buy-in here would be difficult. I'm happy to push to have that discussion, but it would need the cooperation of a handful of repositories. I'll bring it up with moderation to see if it would feel in-scope for the organization and coordinate a forum among the maintainers, if so.

I think that the points you mentioned about the PR template applies to the majority of the other repos as well, so this could be shared as well.

Some parts, yes, but the Generation 1-3 repositories are all quite mature at this point, and so their needs won't necessarily match the needs of the Generation 4 repositories.

Throwing the question here, would an issue template be good as well?

Probably quite a few of them, yes! We'll need to brainstorm what would be good to track.

Also, about check-lists in PR templates, I find them annoying. They are just things you'll have to check each time you open a PR, even though you already know what to check by your second PR.

I agree, but I am willing to acquiesce on it from a personal standpoint if others feel that it's worthwhile, hence my bringing it up for discussion.

Staying on the topic of code formatting verification, I think the better experience is to have a CI that checks that (we already have) and, if it doesn't pass, a bot could comment on the PR with what failed, why it failed, and how to fix it. Potentially only commenting for first-time contributions. Potentially deleting its comment after the issue is fixed to avoid polluting the comment feed.

We've had a discussion in the past about how we might feel about automated changes like these winding up in the repository, and I believe that the consensus at that time was that we did not want them. The grounds for that consensus, as I recall, were that it would require users to pull from their own Pull Request if they forgot to update the formatting. But, the repository and the faces of its contributors look very different now, and I think that it would be good to have that discussion again. Moreover, I think that we can make the automated-format tooling itself much easier to integrate.

I personally leverage pre-commit a lot in my personal projects, including some of the tooling that I've built for this very repository. There is a hook for clang-format in that ecosystem which allows for version-pinning of clang-format itself and installs the tool as a Python wheel, which would make the existing user-woes with the script that we provide in .githooks/pre-commit virtually disappear for the cost of a YAML dot-file. It even has a CI runner, but I have not used it nor looked into it much.

[Kuruyia]

We've had a discussion in the past about how we might feel about automated changes like these winding up in the repository, and I believe that the consensus at that time was that we did not want them.

Oh my idea didn't even go as far as automatically applying the fix on the PR, I was merely saying to automatically add a comment on the PR to inform the contributor about a manual action that needs to be done on their end (which would at least avoid the need for someone else to manually send that exact comment)...

But, the repository and the faces of its contributors look very different now, and I think that it would be good to have that discussion again.

...but I do agree this is something that may be worth discussing! Using pre-commit makes sense to me.

[CharlesFolz4]

The Debugger Support section of INSTALL.md could probably benefit from improvement- it only mentions that a tool exists, and where to get it, but not how to use it. That might be beyond the scope of what should go in ``INSTALL.md`, but the provided information discoverable from there is insufficient for someone who does not already have the prerequisite knowledge about it.