Skip to content

Commit

Permalink
docs: PR title generator & update contributing guideline (#4812)
Browse files Browse the repository at this point in the history
* fix: use relative path

* feat: save `semantic.json`

* chore: update scopes

* ci: auto update mod list

* docs: PR title generator

* docs: remove `Summary` section

was being unused and potentially confusing

* docs:  visible PR template checklist

* docs: advice against commiting on `main`

---------

Co-authored-by: nocontribute <>
  • Loading branch information
scarf005 authored Jun 16, 2024
1 parent 95cb1e5 commit fdc09d8
Show file tree
Hide file tree
Showing 8 changed files with 267 additions and 50 deletions.
67 changes: 38 additions & 29 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,49 @@ If you use GitHub's web editor to edit files, you shouldn't need to do this as t
PR TITLE: Please follow Conventional Commits: https://www.conventionalcommits.org
This makes it clear at a glance what the PR is about.
For example:
feat(content, mods/DinoMod): new dinosaur species
feat(content,mods/DinoMod): new dinosaur species
For more info on which categories are available, see: https://docs.cataclysmbn.org/en/contribute/changelog_guidelines/
If the PR is a port or adaptation of DDA content, please indicate it by adding "port" in PR title, like:
feat(port): <feature name> from DDA
-->

## Checklist

<!--
Certain common types of PRs may need additional code or documentation changes that are easy to forget about or may not be obvious if you're a new contributor. The checklists below should help you track down what else may need to be done.
Please uncomment any relevant checklists, follow their steps and tick the checkboxes once you're done. If your PR does not fall under these categories, you can ignore these lists. If you have any questions or advice on how to improve these, feel free to contact us on our Discord server.
--->

### Required

- [ ] I wrote the PR title in [conventional commit format](https://docs.cataclysmbn.org/en/contribute/changelog_guidelines/).
- [ ] I ran the [code formatter](https://docs.cataclysmbn.org/en/contribute/contributing/#code-style).
- [ ] I linked any relevant issues using [github keyword syntax](https://docs.cataclysmbn.org/en/contribute/contributing/#pull-request-notes) so it can be closed automatically.
- [ ] I have [committed my changes to new branch that isn't `main`](https://docs.cataclysmbn.org/en/contribute/contributing/#make-your-changes) so it won't cause conflict when updating `main` branch later.

### Optional

<!-- please remove sections irrelevant to this PR. -->

- [ ] This PR ports commits from DDA or other cataclysm forks.
- [ ] I have attributed original authors in the commit messages adding [`Co-Authored-By`](https://docs.github.com/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) in the commit message.
- [ ] I have linked the URL of original PR(s) in the description.
- [ ] This is a C++ PR that modifies JSON loading or behavior.
- [ ] I have documented the changes in the appropriate location in the `doc/` folder.
- [ ] If documentation for this feature does not exist, please write it or at least note its lack in PR description.
- [ ] New localizable fields need to be added to the `lang/bn_extract_json_strings.sh` script if it does not support them yet.
- [ ] If applicable, add checks on game load that would validate the loaded data.
- [ ] If it modifies format of save files, please add migration from the old format.
- [ ] This is a PR that modifies build process or code organization.
- [ ] Please document the changes in the appropriate location in the `doc/` folder.
- [ ] If documentation for this feature or process does not exist, please write it.
- [ ] If the change alters versions of software required to build or work with the game, please document it.

- [ ] This is a PR that removes JSON entities.
- [ ] The removed JSON entities have new entries in `data/json/obsoletion/` folder or use some other migration process for existing saves.


## Purpose of change

<!--
Expand Down Expand Up @@ -54,31 +91,3 @@ Remember to attribute the original author(s): if you've just copied over the cha
## Additional context

<!-- Add any other context (such as mock-ups, proof of concepts or screenshots) about the feature or bugfix here. -->

## Checklist

<!--
Certain common types of PRs may need additional code or documentation changes that are easy to forget about or may not be obvious if you're a new contributor. The checklists below should help you track down what else may need to be done.
Please uncomment any relevant checklists, follow their steps and tick the checkboxes once you're done. If your PR does not fall under these categories, you can ignore these lists. If you have any questions or advice on how to improve these, feel free to contact us on our Discord server.
For all Pull Requests:
- [ ] I wrote the PR title in conventional commit format, see above
- [ ] I ran the code formatter
- [ ] I linked any relevant issues using github keyword syntax
If this is a C++ PR that modifies JSON loading or behavior:
- [ ] Document the changes in the appropriate location in the `doc/` folder.
- [ ] If documentation for this feature does not exist, please write it or at least note its lack in PR description.
- [ ] New localizable fields need to be added to the `lang/bn_extract_json_strings.sh` script if it does not support them yet.
- [ ] If applicable, add checks on game load that would validate the loaded data.
- [ ] If it modifies format of save files, please add migration from the old format.
If this is a PR that modifies build process or code organization:
- [ ] Please document the changes in the appropriate location in the `doc/` folder.
- [ ] If documentation for this feature or process does not exist, please write it.
- [ ] If the change alters versions of software required to build or work with the game, please document it.
If this is a PR that removes JSON entities:
- [ ] The removed JSON entities have new entries in `data/json/obsoletion/` folder or use some other migration process for existing saves.
-->
5 changes: 4 additions & 1 deletion .github/semantic.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,9 @@ scopes:
- mods/No_Ferals
- mods/No_Fungi
- mods/No_Rail_Stations
- mods/No_Wasps
- mods/Old_Mutations
- mods/Only_Wildlife
- mods/pride_flags
- mods/RL_Classes
- mods/StatsThroughSkills
- mods/UDP_BN_FAKE_SNOW
Expand All @@ -61,6 +61,7 @@ scopes:
- mods/elevated_bridges
- mods/fuji_mpp
- mods/generic_guns
- mods/innawoods
- mods/limit_fungal_growth
- mods/magiclysm
- mods/manualbionicinstall
Expand All @@ -79,7 +80,9 @@ scopes:
- mods/no_rivtech_guns
- mods/no_scifi
- mods/no_survivor_armor
- mods/no_zombify
- mods/novitamins
- mods/pride_flags
- mods/ruralbiome
- mods/saveload_lua_test
- mods/sees_player_hitbutton
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/autofix.yml
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,4 @@ jobs:
run: |
deno lint
deno test
deno run --allow-read --allow-write scripts/semantic.ts
89 changes: 89 additions & 0 deletions doc/src/assets/semantic.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
{
"types": [
"feat",
"fix",
"docs",
"style",
"refactor",
"perf",
"test",
"build",
"ci",
"chore",
"revert"
],
"scopes": [
"content",
"UI",
"i18n",
"balance",
"port",
"mods/DinoMod",
"mods/FujiStruct",
"mods/Graphical_Overmap",
"mods/Graphical_Overmap_Fujistruct",
"mods/Graphical_Overmap_More_Locations",
"mods/Graphical_Overmap_Urban_Development",
"mods/MMA",
"mods/Mundane_Zombies",
"mods/No_Acid_Zombies",
"mods/No_Anthills",
"mods/No_Bees",
"mods/No_Big_Zombies",
"mods/No_Blobs",
"mods/No_Explosive_Zombies",
"mods/No_Ferals",
"mods/No_Fungi",
"mods/No_Rail_Stations",
"mods/No_Wasps",
"mods/Old_Mutations",
"mods/Only_Wildlife",
"mods/RL_Classes",
"mods/StatsThroughSkills",
"mods/UDP_BN_FAKE_SNOW",
"mods/Zombie_Nightvision",
"mods/aftershock",
"mods/alt_map_key",
"mods/cbm_slots",
"mods/classic_zombies",
"mods/craftgp",
"mods/crazy_cataclysm",
"mods/crt_expansion",
"mods/desertpack",
"mods/disable_lifting",
"mods/elevated_bridges",
"mods/fuji_mpp",
"mods/generic_guns",
"mods/innawoods",
"mods/limit_fungal_growth",
"mods/magiclysm",
"mods/manualbionicinstall",
"mods/modular_turrets",
"mods/more_classes_scenarios",
"mods/my_sweet_cataclysm",
"mods/no_filthy_clothing",
"mods/no_flaming_weapons",
"mods/no_hope",
"mods/no_medieval_items",
"mods/no_mutagen",
"mods/no_npc_food",
"mods/no_olg_guns",
"mods/no_religious_Texts",
"mods/no_reviving_zombies",
"mods/no_rivtech_guns",
"mods/no_scifi",
"mods/no_survivor_armor",
"mods/no_zombify",
"mods/novitamins",
"mods/pride_flags",
"mods/ruralbiome",
"mods/saveload_lua_test",
"mods/sees_player_hitbutton",
"mods/sees_player_retro",
"mods/smart_house_remote_mod",
"mods/speedydex",
"mods/stats_through_kills",
"mods/teleportation_tech",
"mods/test_data"
]
}
109 changes: 109 additions & 0 deletions doc/src/components/Conventional.astro
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
import json from "../assets/semantic.json"
const generalScopes = json.scopes.filter((scope) => !scope.startsWith("mods/"))
const modScopes = json.scopes.filter((scope) => scope.startsWith("mods/"))
---

<style>
optgroup,
label,
select,
select[name="scope"] option {
margin-top: 0 !important;
}
input {
width: 100%;
}
input:disabled {
background-color: var(--sl-color-gray-6);
}
fieldset {
display: grid;
grid-template-columns: max-content 1fr;
gap: 1rem;
}

fieldset label {
justify-self: end;
}
</style>

<script>
// well this isn't very great but it was quick and dirty to write

const outputElem = document.querySelector("input[name=output]") as HTMLInputElement
const typeElem = document.querySelector("select[name=type]") as HTMLSelectElement
const scopeElems = document.querySelectorAll(
"select[name=scope] optgroup option",
) as NodeListOf<HTMLOptionElement>

const subjectElem = document.querySelector("input[name=subject]") as HTMLInputElement

let type = typeElem.value
let subject = subjectElem.value
const scopes = new Set()

const updateOutput = () => {
outputElem.disabled = type.length === 0 || subject.length === 0

const output = `${type}${scopes.size ? `(${Array.from(scopes).join(",")})` : ""}: ${subject}`
outputElem.value = output
}

typeElem.addEventListener("change", (e) => {
type = (e.target as HTMLSelectElement).value
updateOutput()
})

scopeElems.forEach((scopeElem) =>
scopeElem.addEventListener("click", (e) => {
const scope = (e.target as HTMLOptionElement).value
scopes.has(scope) ? scopes.delete(scope) : scopes.add(scope)
updateOutput()
}),
)

subjectElem.addEventListener("input", (e) => {
subject = (e.target as HTMLInputElement).value
updateOutput()
})

// initialize state
updateOutput()

// clipboard
document.querySelector("form")!.addEventListener("submit", (e) => {
e.preventDefault()
navigator.clipboard.writeText(outputElem.value)
})
</script>

<form>
<fieldset>
<label for="type">Type</label>
<select name="type" required>
<option value="">select type</option>
{json.types.map((type) => <option value={type}>{type}</option>)}
</select>
<label for="scope">Scope</label>
<select name="scope" multiple size="6">
<optgroup label="general">
{generalScopes.map((scope) => <option value={scope}>{scope}</option>)}
</optgroup>
<optgroup label="mods">
{modScopes.map((scope) => <option value={scope}>{scope}</option>)}
</optgroup>
</select>
<label for="subject">Subject</label>
<input
type="text"
name="subject"
placeholder="summarize what does this PR does here"
required
/>
</fieldset>
<label for="output">Output</label>
<input type="text" name="output" />
<button type="submit">copy to clipboard</button>
</form>
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,20 @@
title: Changelog Guidelines
---

import Conventional from "../../../../components/Conventional.astro"

## PR Title Generator

<Conventional />

---

PR title follows [Convensional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for easier
changelog generation. The format is one of:

```
<Category>: <PR subject>
<Category>(<Scope>, <Scope>, ...): <PR subject>
<Type>: <PR subject>
<Type>(<Scope>, <Scope>, ...): <PR subject>
```

For Example, a PR title can be:
Expand All @@ -17,9 +25,10 @@ feat: add new mutation
feat(content, port): port mutation description from DDA
```

## Category

The category is the first word in the PR title. They specify the type of change being made. When in
## Type

The type is the first word in the PR title. They specify the type of change being made. When in
doubt, use `feat` for new features, and `fix` for bugfixes. Here are some frequently used
categories:

Expand Down Expand Up @@ -147,5 +156,5 @@ feat(balance): Give moose pelts instead of hides
Example PR title:

```
feat(content, port): game shop
feat(content,port): game shop
```
14 changes: 0 additions & 14 deletions doc/src/content/docs/en/contribute/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,20 +253,6 @@ for it, and will prevent anything that isn't completely ready from being merged
It is not required to solve or reference an open issue to file a PR, however, if you do so, you need
to explain the problem your PR is solving in full detail.

### All PRs should have a `"Summary"` line

Summary is a one-line description of your change that will be extracted and added to the
[project changelog](../game/changelog/index.md)

The format is: `SUMMARY: Category "description"`

The categories to choose from are: Features, Content, Interface, Mods, Balance, Bugfixes,
Performance, Infrastructure, Build, I18N.

Example: `SUMMARY: Content "Adds new mutation category 'Mouse'"`

See the [Changelog Guidelines](./changelog_guidelines.md) for explanations of the categories.

### Closing issues using keywords

One more thing: when marking your PR as closing, fixing, or resolving issues, please include this
Expand Down
Loading

0 comments on commit fdc09d8

Please sign in to comment.