From e7c6973bf139076cc5848cfc959790db5b90172a Mon Sep 17 00:00:00 2001 From: mirrorcult Date: Mon, 23 Mar 2026 18:00:05 -0700 Subject: [PATCH] Update conventions for hardfork --- src/coding/code-conventions.md | 41 +++++++++++++--------------------- 1 file changed, 16 insertions(+), 25 deletions(-) diff --git a/src/coding/code-conventions.md b/src/coding/code-conventions.md index 4ca52fd..d807aa6 100644 --- a/src/coding/code-conventions.md +++ b/src/coding/code-conventions.md @@ -1,12 +1,18 @@ # Code Conventions -In addition to the basic [upstream conventions](https://docs.spacestation14.com/en/general-development/codebase-info/conventions.html), Ephemeral Space has a multitude of custom conventions meant to aid in maintainability and reduce merge conflicts. +```admonish warning +These documents have recently changed significantly as a result of our hardfork. Even if this doc looks the same to you, you should reread the conventions to ensure you understand the new conventions going forward. +``` + +In addition to the basic [upstream conventions](https://docs.spacestation14.com/en/general-development/codebase-info/conventions.html), Ephemeral Space has a multitude of custom conventions meant to aid in maintainability. + +**Ephemeral Space is a hardfork of the upstream repository**. This means we have no qualms about editing or deleting upstream files en masse, and things which we have no use for are generally deleted from the repository entirely. We may occasionally cherrypick and backport commits, but we do not regularly merge in upstream, and we handle engine updates ourselves. ## General Conventions ### Mirrored Directories -When adding new files to the Ephemeral Space project, always include them under an "`_ES`" directory. +When adding *new* files to the Ephemeral Space project, always include them under an "`_ES`" directory. Each project receives its own corresponding directory (`Content.Client/_ES/`, `Content.Shared/_ES/`, etc.) with the file structure of the `_ES` directory mirroring the folder it is in. This is similarly done for each folder inside the `Resources` directory (`Resources/Prototypes/_ES`, `Resources/Textures/_ES`, etc.) @@ -15,30 +21,15 @@ The goal of this is to organize specific Ephemeral Space contributions while mai ### Fork Markers -All modifications to non-_ES files should be enclosed with the `ES START` and `ES END` markers, denoting that the edits were made to the Ephemeral Space project. - -When making modifications, prefer to limit their size and place markers around as little code as possible. -Ideally, all the lines within the markers should have been modified. - -#### File Markers - -When extensive modifications must be made to non-_ES files, prefer to create a header at the beginning of the file to denote the changes. -This helps anyone in the future to see that the entire file has been modified. - -### Prefer Creating Over Editing - -When faced with the option of editing an existing file or creating a new one, prefer creating new _ES-specific files. -Limiting the amount of modifications made is ideal for development. +All C# files that are modified should have an `ES MODIFIED` marker near the start of the file, along with a comment detailing the edits made. In other files, like YAML, no markers are required. ## C# Conventions ### Class Prefixes -All classes and structs should be prefixed with "ES". +All **data definitions** types (components, prototypes, anything else serializable) should be prefixed with "ES". Any other classes, like systems, do not need to be prefixed. -### Prototype Prefixes - -Prototypes, like other classes, should be prefixed with "ES". The name must be explicitly specified in the `PrototypeAttribute` to prevent improper casing. +Prototype names must be explicitly specified in the `PrototypeAttribute` to prevent improper casing. Bad: ```csharp @@ -60,14 +51,14 @@ public sealed class ESTestCasePrototype : IPrototype ### ID Prefixes -All prototypes should have their ID's prefixed with "ES". +We previously required ID prefixing in YAML, but **it is not a convention anymore**. YAML IDs for new prototypes should not be prefixed with `ES`. Pre-hardfork prototypes may still be prefixed with `ES`. ## Spriting Conventions ### RSIs -New sprites made for Ephemeral Space should always be placed inside new RSIs in mirrored directories, similar to prototypes. +Entirely new sprites made for Ephemeral Space should always be placed inside new RSIs in mirrored directories, similar to prototypes. + +If a sprite is a simple replacement of a pre-existing sprite in the game, the upstream RSI should be edited. -If a sprite replaces a pre-existing sprite in the game, it's fine to simply replace the entire RSI. -However, this should only be done if the new RSI is entirely replaced and is not likely to be modified again in the future. -RSIs that are frequently modified (`computers.rsi`, `module.rsi`, `pda.rsi`) should never be modified in part, as they are likely to cause conflicts that are difficult to resolve. +If editing an upstream RSI requires adding new states or removing states, the entire upstream RSI should be **moved to our folder**, and the changes made there. Note that this doesn't say duplicate--move the folder, duplicating is somewhat costly. \ No newline at end of file