Part 3: Maintainer Documentation

Section 1: Workflows Documentation

1.1: General Information

Prerequisites:

Most workflows require:

Relevant Secrets Set (These are Environment Variables if running locally)
- CFCORE_API_TOKEN (a CurseForge API Key)
- CURSEFORGE_API_TOKEN (a personal CurseForge API Token)
- CURSEFORGE_PROJECT_ID (the project ID of the modpack, currently 594351).
A tag before the current tag or commit (on the chosen branch).
- This is needed for the changelog task, and all other workflows which have the changelog task as a step.

The Test Fork PR Workflow requires:

An environment, called fork-pr-build-pack, which contains:
- Permissions Set (needs admin approval to run)
Workflows running on PRs from ALL OUTSIDE COLLABORATORS need approval

Activating the workflow on another branch

If you want the workflow to run on a branch, which isn't main, change the top option (Use workflow from...). This will cause the workflow to run all operations, such as build or making a release commit, on that branch.
Note that this will use the workflow file, and the TypeScript files, from that branch!

Re-running jobs

All of the combined workflows are split into jobs. If one fails, for example, when deploying the release, if deploying to CurseForge fails, then if the other jobs are allowed to run, they will continue to run.

To re-run it, click the Re-run Jobs button. There are two options:

Re-run failed jobs will re-run all failed jobs, and their dependencies. This is useful in the example, where the pack will be built again and deployed to CurseForge, without deploying to GitHub Releases again. This is what should be used typically.
Re-run all jobs will re-run all jobs.

Re running jobs uses the same workflow file, even if the file was changed, and uses the same original inputs.

1.2: Create Changelog

The workflow allows for fast, detailed and consistent changelogs every update.

This workflow does not run automatically.

This workflow uploads both generated changelogs (GitHub & CF) as an artifact.

When run, the options are (excluding the branch selection available to all workflows):

Name	Description	Optional?
Tag	The tag to checkout. This will be the newest commit parsed for the changelog. The TypeScript files will also be used from this tag.	No
Release Type	Must be one of `Release`, `Beta Release` or `Alpha Release`. The Release Type of the release. This will be used in the title at the beginning of the changelog.	No
Compare Tag	Tag to compare against. The changelog will contain all commits after the `Compare Tag`, up to and including the `Tag`.	Yes. If not set, will use the tag before `Tag`.
Branch	Branch to push Changelog to. They will be pushed to the Root Directory. Intended for use with the Deploy to GitHub Releases and CurseForge workflow.	Yes. If not set, changelogs will just be uploaded as an artifact.

Important Note:
The branch input cannot have the same name as the input tag, or any other tag present!
This will cause the commit push to crash!
It is recommended to have the branch name be <tag>-changelog to make it easily differentiable, and to avoid problems!

There are two parts to the changelog:

Changelog Sections: These provide a seperated and neat list of the changes that have occurred.
Commit List: This is a commit list, that is sorted by date, and is filtered.

There are two categories of commits:

Primary Commits: a commit that edits files in /overrides or manifest.json.
Secondary Commits: a commit that does not edit files in /overrides or manifest.json.

There are two changelogs generated:

CHANGELOG.md: The changelog for use in GitHub Releases, and to put into the pack. Written in markdown, and some small html (to center elements).
CHANGELOG_CF.md: The changelog for use in CurseForge Releases. Written in pure html.

If no Commit Keys are set, then:

Primary Commits: the commit message will be put into the General Category, and its Other Sub Category, and the changelog commit log.
Secondary Commits: will not be included in any changelog section, or the changelog commit log.

If commit keys are given, then whatever the commit edits, the commit key will be applied to it. This means that it will be added to the changelog (unless the skip key is used).

Mod Update Commits should contain the No Category Key, as they will be placed in their corresponding mod change section. However, if they fix a bug, or implement a feature, or etc., they should have the corresponding key, and include details.

Mod Change Sections are calculated based on the change in manifest.json, not by commits. The commit SHAs and Authors are added by going through the commits, looking for one that edits that projectID.

If you would like to check your commit, you can run the createChangelog npx gulp task locally, with the env variable TEST_CHANGELOG set to a non-empty string. This will output an error if it occurred, and will otherwise output a changelog to your local repo's root directory.

The output changelogs will contain two keys. These are surrounded by {{{. These are only replaced by their correct values once they are added to their respective release locations.

You can add more of these tags, or remove them, and there can be a different amount

`{{{ CENTER_ALIGN }}}`

This is replaced by the relevant html style attribute, to center text and images in both changelogs. Note that for some reason, currently, images cannot be center aligned in the CF changelog!

`{{{ CF_REDIRECT }}}`

This is replaced by nothing in the GitHub Release, and it is replaced by:
Looks way better here.
with the here linking to the GitHub Release.

Commit Keys:

These keys do something to the commit that they are added to. These are added to the commit's bodies/descriptions.

Add the key part of the commit key to a commit's body to apply it to that commit!

When merging PRs, make sure that no keys are present, or there may be big problems, or unexpected parsing!

List of all Keys:

Intended for use to check for unexpected keys in commit descriptions.
To be safe, avoid all use of []!

Key	Description
Special Effect Keys:
`[SKIP]`	Skips parsing for the commit.
`[EXPAND]`	Expands a commit into subcommits.
`[DETAILS]`	Adds submessages to a commit.
`[NO CATEGORY]`	Puts the commit in the changelog commit list, but not in the sections.
Category Keys:
`[BREAKING]`	Breaking Changes
`[BALANCING]`	Balancing Changes
`[PERFORMANCE]`	Performance Improvements
`[FEATURE]`	Feature Additions
`[QB]`	Quest Book Changes
`[BUG]`	Bug Fixes
`[GENERAL]`	General Changes
`[INTERNAL]`	Internal Changes
Sub Category Keys:
`[NM]`	Normal Mode
`[HM]`	Hard Mode
`[QOL]`	Quality Of Life

Special Effect Keys

These keys are arranged in priority, as only one will take effect. Unless otherwise said, this prevents all other commit keys from taking effect.

Skip Key

Key: [SKIP]

Prevents the commit from being parsed. More simply put, it prevents the commit from showing up in the changelog sections, or in the changelog commit log.

Not needed for Secondary Commits, as this is the default behaviour, if no commit keys are in the commit description.

Expand Key

Key: [EXPAND]

This key essentially creates more commits in the commit, while not adding the original commit to the changelog sections.

The 'subcommits' are stored between two [EXPAND]. These must surround it, with nothing else in them. The key at the beginning must be the first appearance of [EXPAND] in the commit description.

The data must have an array, with key messages, of 'subcommit' objects. The subcommit objects must contain a key messageTitle, which is the message title to add to the changelog section, and optionally contain a key messageBody, which can be used to place the commit in a Category and/or Sub Category, further expansion, and/or to add details to the commit.

The presence of this key prevents any further parsing of the original commit body, although the commit body in each 'subcommit' object will be parsed.

The syntax is in TOML. It is highly recommended you check the syntax here first.

Below is an example of a valid commit body, and its output.

Commit Body:

- Rids QB Again!
- Bears
& more!

[EXPAND]
[[messages]]
  messageTitle = "Rids QB. AGAIN!!!!"
  messageBody = "[QB]"

[[messages]]
  messageTitle = "Nothing. At least I no longer hate this."
  messageBody = '''
  [QB]
  [HM]
  '''

[[messages]]
  messageTitle = "Bears."
  messageBody = """
  [FEATURE]
  [HM]
  - Five Teddies
  - Two Bears
  [DETAILS]
    details = [
    \"Five Teddies\",
    \"Two Bears\",
    \"\"\"
      [DETAILS]
      details = [
      \\"BEARS WILL INVADE NOMI!\\",
      \\"\\"\\"
        [DETAILS]
        details = [ \\\"BEARS WILL INVADE NOMI!\\\" ]
        [DETAILS]
      \\"\\"\\" ]
      [DETAILS]
  \"\"\"
    ]
  [DETAILS]
  BEARS WILL INVADE NOMI!
  """

[[messages]]
  messageTitle = "Expand Time."
  messageBody = """
  [EXPAND]
  [[messages]]
    messageTitle = \"Done. OR IS IT????\"
    messageBody = \"\"\"
    [FEATURE]
    [QOL]
    \"\"\"
  [EXPAND]
  """
[EXPAND]

/* Commits: */
* Thyme to leave.
* Stop Reading this
* GReAt
* Article

Output (Snipped from Changelog, with Commit Authors and SHAs removed):

## Feature Additions:
### Quality Of Life:
* Done. OR IS IT????

### Hard Mode:
* Bears.
    * Five Teddies
    * Two Bears
        * BEARS WILL INVADE NOMI!
            * BEARS WILL INVADE NOMI!

## Quest Book Changes:
### Both Modes:
* Rids QB. AGAIN!!!!

### Hard Mode:
* Nothing. At least I no longer hate this.

As seen, there can also be text before and after this. It is recommended to have a 'human readable version' above.

Here are some notes:

[EXPAND] which are before the ending key must be indented.
The [EXPAND] surrounding the data must be without indents.
For every layer (such as the three layer details in the subcommit Bears.), an extra backslash is needed before the double quotes.
You cannot include the Skip Key anywhere, else this commit will not be parsed!
Every other key can be included in the subcommits.
Including other commit keys in the base commit body will do nothing.
A No Category key in a subcommit will act like a [SKIP] for that subcommit, as these subcommits are not added to the changelog commit list
The base commit would still be added to the changelog commit list.

Details Key

Key: [DETAILS]

This key adds indented details beneath your commit.

The messages are stored between two [DETAILS]. These must surround it, with nothing else in them. The key at the beginning must be the first appearance of [DETAILS] in the commit description.

The data must have an array, with key details, of strings, which contain the details.

You can have multiple layers!

The syntax is in TOML. It is highly recommended you check the syntax here first.

Below is an example of a valid commit body, and its output.

Commit Body:

[FEATURE]
[HM]

- Five Teddies
- Two Bears
  - BEARS WILL INVADE
    - NOMI
[DETAILS]
details = [
  "Five Teddies",
  [
    "BEARS WILL INVADE NOMI!",
    ["BEARS WILL INVADE NOMI!"],
    "Will They?",
  ],
  "Two Bears",
]
[DETAILS]
BEARS WILL INVADE NOMI!

Output (Snipped from Changelog, with Commit Authors and SHAs removed):

## Feature Additions:
### Hard Mode:
* Bears.
    * Five Teddies
        * BEARS WILL INVADE NOMI!
            * BEARS WILL INVADE NOMI!
        * Will They?
    * Two Bears

As seen, there can also be text before and after this. It is recommended to have a 'human readable version' above.

Here are some notes:

[DETAILS] which is before the ending key must be indented.
The [DETAILS] surrounding the data must be without indents.
To add multiple layers, you simply have nested arrays.
You cannot include the Skip Key anywhere, else this commit will not be parsed!
A No Category key in this commit will not do anything.
The commit, and its subcommits, are placed in the changelog in accordance with commit keys in the commit body. If none are set, there are placed according to the defaults.

No Category Key

Key: [NO CATEGORY]

This commit just places the commit in the changelog commit log, and does not place it in any changelog section.

Category Keys

These place a commit in a category. To use them, include the Category Key in the description of your commit, with optional Sub Category Keys.

Commits can go in multiple categories.

The category list is arranged by the order of which they appear in the changelog.

If a commit is allowed entry into a category, it will go into a Sub Category. It can only go in one.

The sub category list of each category determines the sub categories in can enter. It is sorted by priority, with the topmost item on the list having the highest piority, and the lowest item having the lowest piority. If no key specifying a sub category is given, then it will be placed in the Default Sub Category.

If the sub category or the default sub category is N/A, then the category has no sub categories.

Category Key	Category Description	Default Sub Category	Sub Categories (`Key`, Description)
`[BREAKING]`	Breaking Changes	N/A	N/A
`[BALANCING]`	Balancing Changes	Both Modes	`[NM]`, Normal Mode `[HM]`, Hard Mode
`[PERFORMANCE]`	Performance Improvements	N/A	N/A
`[FEATURE]`	Feature Additions	Both Modes	`[QOL]`, Quality Of Life `[NM]`, Normal Mode `[HM]`, Hard Mode
`[QB]`	Quest Book Changes	Both Modes	`[NM]`, Normal Mode `[HM]`, Hard Mode
`[BUG]`	Bug Fixes	Both Modes	`[NM]`, Normal Mode `[HM]`, Hard Mode
`[GENERAL]`	General Changes	N/A (Mod Changes Sub Categories are parsed separately)	N/A
`[INTERNAL]`	Internal Changes	N/A	N/A

1.3: Create Release Commit

This workflow allows for streamlined, worry free and consistent release commits. These commits split up the commit logs nicely, and change relevant parts, such as window titles (in Random Patches Config) and Issue Templates to the new version.

This workflow does not run automatically.

This workflow uploads no artifacts.

When run, the options are (excluding the branch selection available to all workflows):

Name	Description	Optional?
Release Version	Will be added to the Issue Templates dropdown, and used to replace all version fields. (aka 1.6.1a, 1.6.1-beta-3, 1.7.3-alpha-5, 1.8, etc.). See version numbering below. This is also the name of the tag generated.	No
Release Type	Must be one of `Release`, `Beta Release` or `Alpha Release`. Will be ignored if not a release.	No
Not Release?	Whether this run is not a release. If the checkbox is selected, then the version above should be the newest current version, and checks for similar version will not be conducted. Furthermore, the commit will not have a tag. Used to update the actual files from changes in the templates. Note that this input is reversed! Checking it will make the commit NOT a release!	Yes

Version Numbering

Nomi-CEu uses a sequential numbering system, although the numbering system for alphas and betas are slightly different.

Releases:
<major>.<minor>.<patch> <emergency-fix>

Major versions are only changed when an extremely big release occurs. This is pretty much never changed. This is a number.

Minor versions are changed every big release. This is a number.

Patches are fixes between each big release. This is a number.

Emergency fixes occur when a patch needs to be removed, due to an extremely large problem. These are letters, starting from a.

For example:
1.6 -> 1.6.1 -> 1.6.1a -> 1.7 -> 1.7.1 -> 1.7.2 -> 1.8 -> ...

Alphas & Betas:
<incoming-release>-<status>-<pre-num> <emergency-fix>

The incoming release is the next release, that this beta puts out to test.

The status is either alpha or beta, dependent on how stable the release is.

The pre-num is a number that increases with each alpha/beta for a certain release. This is a number, starting from 1.

Emergency fixes occur when a alpha/beta needs to be removed, due to an extremely large problem. These are letters, starting from a.

For example:
1.6 -> 1.6.1-alpha-1 -> 1.6.1-beta-2 -> 1.6.1-beta-3 -> 1.6.1-beta-4 -> 1.6.1 -> 1.6.1a -> 1.7-beta-1 -> ...

1.4: Deploy to GitHub Releases and CurseForge

This workflow allows for a streamlined, fast and reliable way to deploy a release to both GitHub Releases and CurseForge.

This workflow does not run automatically.

This workflow uploads all three built zips (client, server & lang) as an artifact.

When run, the options are (excluding the branch selection available to all workflows):

Name	Description	Optional?
Tag	The tag to checkout. This will be the newest commit parsed for the changelog, if one is generated. This will also be the version number used for the release. The TypeScript files will also be used from this tag.	No
Release Type	Must be one of `Release`, `Beta Release` or `Alpha Release`.	No
Changelog URL	Where to download the Changelog File from. This must be a link to a file. (Raw file if hosted on GitHub). For this to be used, the `Changelog CF URL` input must also be filled in!	Yes
Changelog CF URL	Where to download the CF Changelog File from. This must be a link to a file. (Raw file if hosted on GitHub). For this to be used, the `Changelog URL` input must also be filled in!	Yes
Changelog Branch	Nomi-CEu branch to download the CF Changelog File from. On that branch, there must be `CHANGELOG.md` and `CHANGELOG_CF.md` in the root directory.	Yes
Compare Tag	The tag to compare to, when generating a changelog. This is only used, and a new changelog only generated, if all of the above three inputs are not filled in!	Yes

The workflow generates a changelog, based on the tag and the compare tag, if the Changelog/Changelog CF URLs and the Changelog Branch inputs are not filled in.
The Changelog Branch input is usually more convenient than the branch input, but the URL inputs are useful when testing in a fork, or the branch input is not working.
The Changelog / Changelog CF URLs have a higher priority than the Changelog branch, if both inputs are filled in.
The Changelog Branch input is intended for use with the create changelog workflow's branch input.
For more information about changelogs, see the create changelog documentation.

1.5: Build Pack

This workflow builds the pack, without having to worry about setting environment variables. Useful to make a Cutting Edge Build. Usually just used as a step in other workflows.

This workflow does not run automatically.

This workflow uploads all three built zips (client, server & lang) as an artifact.

When run, the options are (excluding the branch selection available to all workflows):

Name	Description	Optional?
Tag	The tag to checkout. This will be the newest commit parsed for the changelog, if one is generated. This will also be the version number used for the release. The TypeScript files will also be used from this tag. If not provided, will just build `HEAD`.	Yes
Release Type	Must be one of `Release`, `Beta Release`, `Alpha Release` or `Cutting Edge Build`.	No
Changelog URL	Where to download the Changelog File from. This must be a link to a file. (Raw file if hosted on GitHub). For this to be used, the `Changelog CF URL` input must also be filled in!	Yes
Changelog CF URL	Where to download the CF Changelog File from. This must be a link to a file. (Raw file if hosted on GitHub). For this to be used, the `Changelog URL` input must also be filled in!	Yes
Changelog Branch	Nomi-CEu branch to download the CF Changelog File from. On that branch, there must be `CHANGELOG.md` and `CHANGELOG_CF.md` in the root directory.	Yes
Compare Tag	The tag to compare to, when generating a changelog. This is only used, and a new changelog only generated, if all of the above three inputs are not filled in!	Yes

For cutting edge builds, all of the inputs can be ignored, apart from changing the Release Type to Cutting Edge Build.

When building a cutting edge build, the changelog title will not contain the default <release-type> <tag>, but will contain Cutting Edge Build <time-date>.

The Cutting Edge Build Release Type is only available for this workflow! It is not available for any other deploy or release related workflow!

1.6: Create Release Commit & Changelog

This workflow combines the create release commit workflow and the create changelog workflow.

Because the create changelog workflow is usually called after the release commit workflow, in order to have a tag to base it off, this workflow combines the two.

For more information on how to use each one, especially the create changelog workflow, go to their pages below.

1.2. Create Changelog
1.3. Create Release Commit

The workflow calls the create release commit workflow first, then calls the create changelog workflow.

This workflow cannot be called automatically.

This workflow uploads both generated changelogs (GitHub & CF) as an artifact.

When run, the options are (excluding the branch selection available to all workflows):

Name	Description	Optional?
Tag	The tag to create, through the release commit workflow's version input. This will also be the version number used for the release.	No
Release Type	Must be one of `Release`, `Beta Release` or `Alpha Release`.	No
Compare Tag	Tag to compare against. The changelog will contain all commits after the `Compare Tag`, up to and including the `Tag`.	Yes. If not set, will use the tag before `Tag`.
Branch	Branch to push Changelog to. They will be pushed to the Root Directory. Intended for use with the Deploy to GitHub Releases and CurseForge workflow.	Yes. If not set, changelogs will just be uploaded as an artifact.

1.7: Release Commit & Deploy

This workflow simply combines the release commit workflow and the deploy to GitHub Releases & CurseForge workflow, although as it does not provide any method of inputting non-generated changelogs, it could also be said to include the [create changelog workflow].

This workflow is meant for releases where the changelog does not need to be edited, and provides a quick and straightforward way to make a release.

For more information on how to use each one, go to their pages below.

1.3. Create Release Commit
1.4. Deploy to GitHub Releases & CurseForge

The workflow calls the create release commit workflow first, then calls the deploy workflow.

When run, the options are (excluding the branch selection available to all workflows):

Name	Description	Optional?
Tag	The tag to create, through the release commit workflow's version input. This will also be the version number used for the release.	No
Release Type	Must be one of `Release`, `Beta Release` or `Alpha Release`.	No
Compare Tag	Tag to compare against. The changelog will contain all commits after the `Compare Tag`, up to and including the `Tag`.	Yes. If not set, will use the tag before `Tag`.

1.8: Update Quest Book Jsons and Lang

This workflow updates the QB Jsons, and the english lang, every time a commit is pushed to main, which changes one, or both, of the Development Json Files.

This is done automatically, although you can also run it manually, if something is out of date, for some reason. Calling the workflow has no additional inputs. (Apart from the branch selection, present in all workflows.)

This workflow uploads no artifacts.

When running automatically, if you want the QB Transform Workflow to run on a branch that isn't main, prefix the branch with test_buildscript.

This workflow is disabled, both when running automatically, and manually, on forks of this repository.

If you want the QB Transform Workflow to run on your fork, remove or comment out if: "${{ github.repository_owner == 'Nomi-CEu' }}" in /.github/workflows/updateqb.yml (in your fork)

1.9: Un-Callable Workflows

Workflows that have their name prefixed with [NOT CALLABLE] are not callable. They are used as steps for other workflows.

1.10: Typical Usage

Releases:
Releases will usually have changes applied to the changelog, such as adding a release picture, or adding notes / more information.

Because of this, this is usually a four step process.

Calling the create release commit & changelog workflow, with the appropriate tag, release type, compare tag, and branch (as usually you want to compare to the last release, and beta/alpha releases also use tags).
Editing CHANGELOG.md and CHANGELOG_CF.md in the produced branch, and committing the changelog changes to that branch.
Calling the deploy to GitHub Releases and CurseForge workflow with the generated tag, the appropriate release type, and the changelog branch input set to the generated branch.
AFTER the workflow finishes, delete the generated branch.

Alpha & Beta Releases:
Alpha and Beta Releases are designed to be simple, perhaps even more than Cutting Edge Builds. There is one step to making these releases.

Calling the release commit & deploy workflow with the appropriate tag/version, release type, and perhaps the tag to compare to (although beta/alpha releases usually compare to the newest tag).

Cutting Edge Builds:
This just simply builds the pack, to allow for quick and worry-free builds. This is usually a two step process:

Calling the build pack workflow with the release type set to Cutting Edge Build, and no other inputs set/changed.
Linking the workflow run to users, telling them to download the pack from the artifacts section, or downloading it yourself, and uploading the zips separately somewhere. The first option is recommended, although the second option may be more convenient for users.

Part 3: Maintainer Documentation

Section 1: Workflows Documentation

1.1: General Information

Prerequisites:

Activating the workflow on another branch

Re-running jobs

1.2: Create Changelog

{{{ CENTER_ALIGN }}}

{{{ CF_REDIRECT }}}

Commit Keys:

List of all Keys:

Skip to:

Special Effect Keys

Skip Key

Expand Key

Details Key

No Category Key

Category Keys

1.3: Create Release Commit

Version Numbering

1.4: Deploy to GitHub Releases and CurseForge

1.5: Build Pack

1.6: Create Release Commit & Changelog

1.7: Release Commit & Deploy

1.8: Update Quest Book Jsons and Lang

1.9: Un-Callable Workflows

1.10: Typical Usage

`{{{ CENTER_ALIGN }}}`

`{{{ CF_REDIRECT }}}`