pokeplatinum/CONTRIBUTING.md

Contributing to pret/pokeplatinum

Welcome! If you're reading this guide, then you probably want to contribute revisions, documentation, or tooling to the project. We value any and all contributions, however small or large. Before getting started, please take a look through this document for some important tips on how to smooth out the experience of your first contribution.

Thanks again, and we look forward to hearing from you! 🎉

Table of Contents

• What work is there to be done?
• How do I set up a development environment?
  • Auto-Completion and Language Server Setup
  • Editor Configuration
  • Code Formatting
• How should I name things?
• I can't find a file that's included; where is it?
• Your First Contribution
  • What must I do before submitting a pull request?
  • How do I submit a pull request?
  • What to Expect

What work is there to be done?

At this stage of its life-cycle, the repository is almost 100% C code, although much of it is obfuscated. Some straggler-routines still linger in ARM assembly, and some small utility libraries also need to be decompiled. As a result, much of the work for this repository at present comes down to documentation and tooling.

If you are looking for a bite-sized work-item to pick out for your first contribution, we maintain a living issue to document files or functions which we have identified as being smaller in scope. Take a look through and see if something strikes your interest! Alternatively, if there is a particular piece of functionality that you want to explore, please reach out to us on Discord for pointers in the right direction.

How do I set up a development environment?

If you haven't already, take the time to read through INSTALL.md and ensure that you can successfully build a matching version of the binary target:

make check

We provide some tooling within the repository to integrate with common developer enhancements.

Auto-Completion and Language Server Setup

We provide some instructions for setting up a variety of popular editors; refer to the documentation snippets in docs/editor_setup to see if your editor has specific instructions. If it is not, you may be able to adapt an existing guide for your preferred editor; if so, feel free to file a pull request with a new guide tailored to that editor!

Editor Configuration

An .editorconfig file exists at the root of the repository, which helps alleviate configuring individual editors to present code identically. Many popular editors will provide support for this integration out-of-the-box with no installation required; others may require a plugin or extension. For details on which is which, refer to this documentation.

Code Formatting

We make use of clang-format for our automated code formatting. Some additional tooling is built into the repository to keep our code-style consistent and alleviate the need for manual upkeep from maintainers via pull requests reviews. To ensure that this style is always upheld, a rule is enabled on the repository that will check that every pull request matches the style guidelines.

The caveat to this is that a contributor must remember to format their code. To smooth out this experience, we:

1. Expose the clang-format build option generated by Meson via a Makefile entry-point. If we are ever unsure if the repository is incorrectly formatted, we can run make format as a manual check to ensure correctness.
2. Integrate clang-format into our commit workflows. We manage this via pre-commit, which allows us to pin the version of clang-format used within the repository and ensure that end-users can easily install it.

[!WARNING] To ensure that a pull request passes our CI checks, it is recommended that you install a version of clang-format which is the same version or more recent as is used in the CI checks. You can verify what version is expected by checking the field version in the file .github/workflows/pr-lint.yml.

[!TIP] It is heavily recommended that you make use of pre-commit as a contributor. Doing so will ensure that you are using the same version of any on-commit tools as all other contributors.

To install pre-commit via a project-local Python virtual environment, run the following commands in sequence:

python -m venv .venv
source .venv/bin/activate.sh
pip install pre-commit

Once the installation completes, you can tell pre-commit to install the configured hooks into your project:

pre-commit install

How should I name things?

The eternal question. Some elements of development cannot be automated via tooling, and we leave these to our best judgment. In general, the following rules apply throughout the repository:

// Use PascalCase for structure names. Include both a structure tag ("struct
// MyStruct") and a typedef ("MyStruct").
typedef struct MyStruct {
    u32 myField; // Use camelCase for member variables.
} MyStruct;

// Use PascalCase for enum names. Unlike structs, do NOT typedef enums.
enum MyEnum {
    // Use UPPER_SNAKE_CASE for enum members. Explicitly label the first member
    // with a direct assignment.
    MY_ENUM_MEMBER = 0,
    MY_ENUM_MEMBER, // Successive members should not have a direct assignment.
};

// Use PascalCase for function names and camelCase for parameters.
static int MyFunction(int myParameter)
{
    int myLocalVariable; // Use camelCase for local variables.
}

// Due to the breadth of the repository and its general structure tending
// towards OOP paradigms, modules tend to prefix their public functions with
// their own name followed by an underscore.
int Module_MyExternalFunction(int myParameter)
{
    //
}

I can't find a file that's included; where is it?

We generate a lot of files through meta-programming utilities. For example, a large number of our named-constants are constructed as part of the build; these live in the source-tree as plain text files in the generated subdirectory. A program picks up these files, e.g., generated/days_of_week.txt:

DAY_OF_WEEK_SUNDAY
DAY_OF_WEEK_MONDAY
DAY_OF_WEEK_TUESDAY
DAY_OF_WEEK_WEDNESDAY
DAY_OF_WEEK_THURSDAY
DAY_OF_WEEK_FRIDAY
DAY_OF_WEEK_SATURDAY

...and transforms them into C headers in the build-tree, e.g., from build/generated/days_of_week.txt:

#ifdef POKEPLATINUM_GENERATED_ENUM

enum DayOfWeek {
    DAY_OF_WEEK_SUNDAY    = 0,
    DAY_OF_WEEK_MONDAY    = 1,
    DAY_OF_WEEK_TUESDAY   = 2,
    DAY_OF_WEEK_WEDNESDAY = 3,
    DAY_OF_WEEK_THURSDAY  = 4,
    DAY_OF_WEEK_FRIDAY    = 5,
    DAY_OF_WEEK_SATURDAY  = 6,
}; /* enum DayOfWeek */

#else

#define DAY_OF_WEEK_SUNDAY    0
#define DAY_OF_WEEK_MONDAY    1
#define DAY_OF_WEEK_TUESDAY   2
#define DAY_OF_WEEK_WEDNESDAY 3
#define DAY_OF_WEEK_THURSDAY  4
#define DAY_OF_WEEK_FRIDAY    5
#define DAY_OF_WEEK_SATURDAY  6

#endif /* POKEPLATINUM_GENERATED_ENUM */

This allows us to make use of a single source of truth for values which should be shared between the compiled C code and the assembly files used to build the game's custom scripting implementation. For example, if included from a C file, the above header-snippet would be treated as enum DayOfWeek with all of the appropriate symbols and enum benefits, whereas an assembler will read the pre-processor definitions instead.

Your First Contribution

You've picked out a feature, documented it, and have maybe even made some commits. Congratulations! You're on the way to your first contribution.

If you are new to git and/or GitHub, take some time to read through The Basics of Git and GitHub from Team Aqua's Asset Repo. While originally written with the target audience of pokeemerald modders in mind, the concepts are still very applicable, and it provides a great overview of the topics and terminology that is often thrown around among more seasoned git users.

What must I do before submitting a pull request?

1. Ensure that a local build of make check returns OK, which signals that your code builds a matching ROM.
2. Format your code such that it matches the repository's style guide. Refer to Code Formatting for instructions on how to do this as an automatic part of your commit workflow or manually before you commit your changes.

We run automated checks via GitHub Actions to ensure that all pull requests meet these requirements. If any of these are not done, then their respective checks will fail, and your pull request will not be accepted.

How do I submit a pull request?

We follow a basic fork-model for pull requests, since it provides the simplest GitHub integration. If you haven't done so already, create a fork for your repository via GitHub, then set it up as your origin:

git remote add pret https://github.com/pret/pokeplatinum.git
git remote set-url origin https://github.com/<YOUR_USER>/pokeplatinum.git

Now that you have a fork, checkout your changes to a clean branch, giving it a name that reflects your work:

git checkout -b <branch_name>

Finally, push to your new fork:

git push -u origin <branch_name>

...and submit your changes for review! 🚀

What to Expect

A maintainer of the repository will respond to your Pull Request at their earliest convenience. If you'd like to communicate with the maintainers more directly, feel free to reach out to us in the #pokeplatinum channel of the pret Discord.

Your pull request will be labeled with new-contributor; this is not a target, we promise! It is just your first welcome aboard the team.

Maintainers are encouraged to follow Conventional Comments, which helps to more clearly convey tone of speech and clarify the goal of a particular piece of feedback. In general, these prefixes can be read as:

1. suggestion: A proposed improvement to the subject.
2. polish: A variant of suggestion where quality can immediately be improved. Applicable to cases where there is nothing wrong with the subject.
3. quibble: A trivial, often preference-based request. Inherently non-blocking.
4. issue: A highlight for a specific problem with the subject. For our use-case, these typically are framed around minimizing wires for users of the repository to trip over.
5. todo: A small, trivial, necessary change.
6. question: A curiosity from the author, often seeking understanding of why the code behaves in the way that it does.
7. thought: An idea that popped up during review. Often left so that we do not lose access to past ideas. Inherently non-blocking.
8. chore: A simple task that must be completed before the subject can be officially accepted. Tends to refer to process (and may indicate opportunities to improve developer tooling).
9. note: A highlight that the reader should notice. Inherently non-blocking.

You may receive a lot of feedback on your first request, and it may feel intimidating. Rest assured that it is not targeted, nor is a newcomer's review more-heavily scrutinized than a long-time contributor's. We all have room to improve. 🙏