guidelines git_specification commits

Conventional Commits for WorldBuilding

Fork of Conventional Commits for Research. Made for WorldBuilding version control repositories - 2026-07-28

[!WARNING] STILL WIP

Introduction

After starting a worldbuilding project on git, i think the commits also need to be neat and tidy like other software projects. I could not find any worldbuilding project GitHub repository to take example from [If there one, please let me know]. Because the existing Conventional Commits specification was designed specifically for software projects, its popular types often fail to capture the unique nuances of worldbuilding activities. Even tho there is no need for a commit system of a worldbuilding activities, it is still fun to play with our available thoughts (Sorry for blabbering, this is my thoughts)

Why Use Conventional Commits for Worldbuildgin ?

• Enabling to skim thru commit history
• Helping neurodivergent people's decision fatigue to name their worldbuilding commits
• Help Automatically-generating CHANGELOGs.
• Communicating the nature of changes to teammates and other stakeholders.

If you already familiar with Conventional Commits, you can navigate directly to Summary. If you want to review document, you might need to also see the Base Logic of this specification.

Summary

The Conventional Commits for worldbuilding specification is a strict convention on top of commit messages, specialized for worldbuilding project stored in version control repositories. It provides a detailed set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention adapted from already existing Conventional Commits, This convention currently dovetail with WorldVer which located in the same repo. This summary section is assuming the reader already familiar with Conventional Commits.

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit contains the same structural elements as Conventional Commits, with addition and changes in types, scopes, and breaking change listed below. This was made to record changes in research process:

1. Universal commit types
   • style: same as formerly Angular Convention's. used in worldbuilding for tagging, formatting documents
   • docs: same as Angular Convention's; used in worldbuilding commits only for non-in-universe documentation.
   • chore: same as formerly Angular Convention's.
   • ci: same as Angular Convention's.
   • revert: same as Conventional Commits.
2. Commit types only for changes in worldbuilding
   • draft: . equivalent mostly to chore but leastly to feat
   • canon: . equivalent to feat
   • refine: . equivalent to refactor and fix
   • asset:
   • world: to group conworlding-only type if the project is code-focused.
3. Commit types only for changes in code [used in research]
   • feat: same as Conventional Commits; also used in research commits for newly acquired raw data.
   • fix: same as Conventional Commits; data can also have bugs and fixes.
   • code: to group type feat, fix, refactor, perf, and style. These grouped types can have their own commit.
   • devtool: to group type build and test. These grouped types can have their own commit.
4. Scope. Even though scope field is optional, there are few recommended predefined scope that can be used
   • for commit type feat and fix, scope data is to represent the new or fixed data.
   • for commit type process, its scope should represent the stage/list of data processing
   • for commit type dissem, its scope should represent the types of dissemination, or part/chapter of the manuscript
   • for commit type method, its scope should represent the stage/list of method being used
5. Breaking changes are retcon
6. The verb of imperative mood should describe the importance of a commit

Examples

• Commit message with scope and ! to draw attention to breaking change

  dissem(intro)!: restructure introduction section for clarity
  

• Commit message with both ! and BREAKING CHANGE footer

  expt(validation)!: replace validation dataset with external benchmark
  
  BREAKING CHANGE: Prior validation results are no longer comparable
  with the new dataset.
  

• Commit message with no body

  docs: correct spelling of CHANGELOG
  

• Commit messages with scope

  feat(data): add new survey responses
  code(refactor): simplify data parser logic
  devtool(test): add unit tests for preprocessing pipeline
  research(process): add provenance metadata for dataset
  

• Commit message with multi-paragraph body and multiple footers

  process(cleaning): correct mislabeled sample IDs
  
  Corrected sample identifiers in dataset to match metadata records.
  This ensures consistency across analysis pipelines.
  
  Reviewed-by: Alice
  Acked-by: Bob
  Refs: #456
  

Full Commit Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1. Commits MUST be prefixed with a type, followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
2. Type consists of a noun. The types in the next three items is used for their own condition.
3. These below are universal commit types, which MAY be used for both research and code commits.
   • The type feat MUST be used when a commit adds a new feature to your code; or adds a new raw data in your research.
   • The type fix MUST be used when a commit represents a bug fix for your codes or data.
   • The type style MAY be used when a commit makes cosmetic changes to code/research that do not affect its behavior/meaning.
   • The type docs MAY be used when a commit makes changes to documentation, comments, or API descriptions; and MUST be used in research commits only for project management (non-scientific) documents.
   • The type ci MUST be used when a commit changes CI (and CD) configuration files and scripts.
   • The type chore MAY be used when a commit contains miscellanous tasks that do not impact production code nor research progress.
   • The type revert MUST be used when rolling back a previous commit.
4. These below are commit types only for changes in research, which MUST only be used for research commits.
   • The type process MUST be used when a commit represents data processing.
   • The type analsynt MUST be used when a commit represents the data is being discussed/analyzed/synthesized.
   • The type dissem MUST be used when a commit makes changes on dissemination documents.
   • The type method MUST be used when a commit makes changes on protocols/procedure/documents of materials and methods.
   • ?The type expt MUST be used when a commit experiments, tests, or validates data/methods. This type confirms correctness, reliability, or reproducibility, and MUST NOT be confused with “experimental research.”.
   • The type research SHOULD NOT be used to group research-only commit types, unless the project is code-focused rather than research-focused.
5. These below are commit types only for changes in code, which MUST only be used for code commits.
   • The type refactor MAY be used when a commit makes structural improvements to the code without changing its behavior.
   • The type perf MAY be used when a commit changes code that improves performance.
   • The type build MAY be used when a commit affects the build system or external dependencies.
   • The type test MAY be used when a commit adds, modifies, fixes, or improves tests on code.
   • The type code SHOULD be used to group type feat, fix, refactor, perf, and style.
   • The type devtool SHOULD be used to group type build and test.
6. A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase/research surrounded by parenthesis, e.g., fix(parser):. Some predefined scopes are listed below.
   • For commit type feat and fix, scope data is RECOMMENDED to represent the new or fixed data.
   • For commit type process, its scopes SHOULD represent the stage/list of data processing.
   • For commit type dissem, its scopes SHOULD represent the types of dissemination, or part/chapter of the manuscript.
   • For commit type method, its scopes SHOULD represent the stage/list of method being used.
   • For commit type research, code, and devtool, its scopes MUST be their grouped type and MAY be other scopes.
7. A description MUST immediately follow the colon and space after the type/scope prefix. It is RECOMMENDED to use imperative mood. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
8. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
9. A commit body is free-form and MAY consist of any number of newline separated paragraphs.
10. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a :<space> or <space># separator, followed by a string value (this is inspired by the git trailer convention).
    1. A footer's token MUST use - in place of whitespace characters, e.g., Acked-by (this helps differentiate the footer section from a multi-paragraph body). An exception is made for BREAKING CHANGE, which MAY also be used as a token.
    2. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed.
11. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer.
    1. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., BREAKING CHANGE: environment variables now take precedence over config files.
    2. If included in the type/scope prefix, breaking changes MUST be indicated by a ! immediately before the :. If ! is used, BREAKING CHANGE: MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change.
12. Types other than those already mentioned above MAY be used in your commit messages.
13. The units of information that make up Conventional Commits MUST NOT be treated as case-sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
14. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.

External Links

This document is licensed with Creative Commons - CC BY 4.0

Conventional Commits are licensed with Creative Commons - CC BY 3.0