Enhance snippet handling

.github/workflows/auto-draft-pr.yaml

@@ -18,7 +18,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-name: Convert PRs to Draft on Opening
+name: Pull Request preparation
 
 permissions:
   contents: write
@@ -31,7 +31,22 @@ jobs:
   convert_to_draft:
     runs-on: ubuntu-latest
     steps:
-      - run: gh pr ready --undo ${{ github.event.pull_request.number }}
+      - name: Add snippet
+        working-directory: changelog/snippets
+        run: |
+          # Configure git
+          git config user.email "github@faforever.com"
+          git config user.name "FAForever Machine User"
+
+          FILE=category.${{ github.event.pull_request.number }}.md
+          cp sections/template-snippet.md $FILE
+          sed -i "s/XYZW/${{ github.event.pull_request.number }}/g" $FILE
+
+          git add .
+          git commit -m "Add snippet template"
+
+      - name: Convert PR to draft
+        run: gh pr ready --undo ${{ github.event.pull_request.number }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}

changelog/snippets/sections/template-snippet.md

@@ -0,0 +1 @@
+- Your explanation here (#XYZW).

docs/Gemfile

@@ -5,3 +5,7 @@ gem "jekyll", "~> 4.3.3" # installed by `gem jekyll`
 
 gem "just-the-docs", "0.8.2" # pinned to the current release
 # gem "just-the-docs"        # always download the latest release
+
+gem "csv", "~> 3.3"
+
+gem "base64", "~> 0.3.0"

docs/Gemfile.lock

@@ -3,22 +3,24 @@ GEM
   specs:
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
+    base64 (0.3.0)
     bigdecimal (3.1.8)
     colorator (1.1.0)
     concurrent-ruby (1.2.3)
+    csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
     ffi (1.16.3)
     forwardable-extended (2.6.0)
-    google-protobuf (4.27.5-arm64-darwin)
+    google-protobuf (4.33.6-arm64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.27.5-x64-mingw-ucrt)
+    google-protobuf (4.33.6-x64-mingw-ucrt)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.27.5-x86_64-linux)
+    google-protobuf (4.33.6-x86_64-linux-gnu)
       bigdecimal
       rake (>= 13)
     http_parser.rb (0.8.0)
@@ -89,6 +91,8 @@ PLATFORMS
   x86_64-linux-gnu
 
 DEPENDENCIES
+  base64 (~> 0.3.0)
+  csv (~> 3.3)
   jekyll (~> 4.3.3)
   just-the-docs (= 0.8.2)
 

docs/_plugins/balance_change.rb

@@ -0,0 +1,13 @@
+#module Jekyll
+#  class BalanceChangeBlock < Jekyll::Hooks
+#  end
+#end
+
+Jekyll::Hooks.register [:pages, :documents], :post_render do |doc|
+
+  doc.output.gsub!(
+    /([^<\s]+)\s*--&gt;\s*([^<\s]+)/,
+    '<span class="old">\1</span> → <span class="new">\2</span>'
+  )
+
+end

docs/_plugins/unit_block.rb

@@ -0,0 +1,23 @@
+module Jekyll
+  class UnitBlock < Liquid::Block
+
+    def initialize(tag_name, markup, tokens)
+      super
+      @unit_id = markup.strip
+    end
+
+    def render(context)
+      name = super.strip
+
+      <<~HTML
+      <div class="unit-header" data-unit="#{@unit_id}">
+        <img class="unit-icon"
+             src="/assets/icons/#{@unit_id}.png">
+        <span class="unit-name">#{name}</span>
+      </div>
+      HTML
+    end
+  end
+end
+
+Liquid::Template.register_tag('unit', Jekyll::UnitBlock)

docs/_sass/custom/custom.scss

@@ -0,0 +1,31 @@
+.unit-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-top: 2rem;
+  font-size: 1.2rem;
+  font-weight: 600;
+}
+
+.unit-icon {
+  width: 64px;
+  height: 64px;
+}
+
+.unit-name {
+  display: inline-block;
+}
+
+.unit-header + ul > li {
+  font-weight: 600;
+}
+
+.old {
+  color: #d73a49;
+  text-decoration: line-through;
+}
+
+.new {
+  color: #2da44e;
+  font-weight: 600;
+}

docs/development-changelog.md

@@ -20,11 +20,9 @@ We use snippets to reduce the burden on maintainers to write an accurate changel
 
 ### Format of a snippet
 
-All current snippets can be found in the [snippets folder](../changelog/snippets/).
-
 The structure of the file name is `XXX.ABCD.md`, where `XXX` is one of the snippet types and `ABCD` is the pull request number. The available snippet types are `fix`, `features`, `balance`, `graphics`, `ai`, `performance` or `other`.
 
-The content of a snippet is similar to a commit message. The first line is a title that starts with the relevant pull requests and a concise description of the changes, as an example: ` - (#PR1, #PR2, ...) <concise description of changes>`. Use a dot at the end of the first line. The remainder of the file can be used to provide additional and more detailed information about the changes. Remember to indent these additional lines, so they follow the indentation that gets created because of the list item of the first line. Add an empty line at the end of the file to make sure that the next snippet is separated by an empty line. You can make use of a Markdown formatter to ensure consistency, one example is the use of [prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
+The format of a snippet depends on whether it is a [balance snippet](../development/changelog/balance-snippet) or [any other category](../development/changelog/other-snippet).
 
 ### Choosing a category
 
@@ -38,10 +36,6 @@ The content of a snippet is similar to a commit message. The first line is a tit
 
 If multiple categories are fitting, use the one that appears first in this list.
 
-### Example snippet
-
-
-
 ## Sources and inspiration
 
 We did not come up with this approach ourselves. We took inspiration from similar solutions of projects that experienced similar problems:

docs/development-changelog/balance-snippet.md

@@ -6,23 +6,57 @@ permalink: development/changelog/balance-snippet
 published: true
 ---
 
-_Information about how to structure a balance snippet_
+The game just renders the text as is, so we need to keep that in mind.
+Unit or explanation first?
+The unitID is also used to infer if the snippet is supposed to go into the land, navy, air, structures or enhancements category.
+if the change is an enhancement, the unitID is enhancements/faction/name
+The md to lua converter should remove the {: .unit-change} and the (unitID)
+
+
 
 The snippet file should be named `balance.<PR Number>.md`.
 
 ```
-- (#<PR Number>) <Description>
-
-  **<Formatted Unit Name> (<Blueprint ID>):**
-  - <Section>
-    - <Parameter Name>: <value before> --> <value after>
-    - <Parameter Name>: <value before> --> <value after>
+{% unit <BlueprintID> %}
+<Formatted Unit Name>
+{% endunit %}
+<Description> (#<PR Number>)
+- <Category>:
+  - <Parameter Name>: <value before> --> <value after>
 ```
 
 - PR Number: The number of the pull request on GitHub.
 - Description: A 1-sentence summary of the changes and then a short explanation behind the reasoning for the changes.
-- Formatted Unit Name: `<UnitName>: <Tech> <Unit Description>` For example: `Exodus: T2 Destroyer`. This is similar to the format visible in unit dbs and the in-game UI when hovering over a unit.
-- Blueprint ID: Blueprint ID of the unit in uppercase.
-- Section: An optional subheader to categorize parameters. Usually a blueprint subtable name (ex: Physics) or a weapon name.
-- Parameter Name: The name for the value that was changed. It shouldn't be the exact blueprint field name; it should be a name that players can understand and formatted like normal text.
+- Formatted Unit Name: `<UnitName>: <Tech> <Unit Role>` For example: `Exodus: T2 Destroyer`. This is similar to the format visible in unit dbs and the in-game UI when hovering over a unit.
+- Blueprint ID: Blueprint ID of the unit.
+- Category: A subheader to categorize parameters. Usually a blueprint subtable name (ex: Physics) or a weapon name.
+- Parameter Name: The name for the value that was changed. It doesn't need to be the exact blueprint field name; it should be a name that players can understand.
 - Value before/after: The value before/after the change. If relevant, derived values like DPS can be put in parentheses after the value as such: `<damage> (<dps>) --> <damage> (<dps>)`.
+
+When the same change has been applied to multiple units, you can just write the group in the title. The unitID still loads the unit icon, so choose a unit that is most representative. (UEF when all factions are affected).
+
+### Example snippets
+
+{% unit URS0201 %}
+Salem Class: T2 Destroyer
+{% endunit %}
+Reduced Salem’s anti-torpedo flare target check interval from 1.0s to 0.4s—the standard for anti-projectile weapons. This improves torpedo detection and flare response, especially against torpedo bombers. In turn the movement speed has been tuned down (#6339).
+- Anti Torpedo:
+    - Target Check Interval: 1s --> 0.4s
+- Movement:
+    - Max speed : 5 --> 4
+
+{% unit UEA0102 %}
+All T1 Interceptors
+{% endunit %} 
+Reduce the distance at which T1 Interceptors hover instead of turning when given a move order (#6342).
+- Air Movement:
+    - Start Turn Distance: 10 --> 5
+
+{% unit enhancements/cybran/torp %}
+Nanite Torpedo Launcher
+{% endunit %}
+Further increase the MuzzleSalvoSize of the Cybran ACU's Nanite Torpedo upgrade to 4, as it still had difficulties penetrating torpedo defenses after (#6476) increased it to 3. Its DPS remains unchanged (#6542).
+- Torpedo weapon:
+    - Damage (DPS): 60 (225) --> 45 (225)
+    - Muzzle Salvo Size: 3 --> 4

docs/development-changelog/other-snippet.md

@@ -6,4 +6,13 @@ permalink: development/changelog/other-snippet
 published: true
 ---
 
-_Information about how to structure all other snippets_
+The content of a snippet that is not in the balance category is similar to a commit message. The first line is a title that starts with a dash followed by a concise description of the changes. Use a dot at the end of the first line. The remainder of the file can be used to provide additional and more detailed information about the changes. Remember to indent these additional lines, so they follow the indentation that gets created because of the list item of the first line. Mention the relevant pull requests at the end of the text like so: `(#PR1, #PR2, ...)`.
+Add an empty line at the end of the file to make sure that the next snippet is separated by an empty line. You can make use of a Markdown formatter to ensure consistency, one example is the use of [prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
+
+### Example snippet
+```
+- Tweak the formula used to calculate the level of detail (LOD) for props.
+
+  Large props are visible for longer, and it should now be easier again to spot broken tree groups (#6906).
+
+```

docs/documentation.md

@@ -27,4 +27,4 @@ In addition we recommend the following tooling:
 To run the documentations website on the localhost you need a command line where the current directory is the `docs` folder. From there you run the following commands:
 
 - `bundle install`: Similar to `npm install` if you're familiar with the Node Package Manager. Should be necessary only once. Installs all relevant packages.
-- `bundle exec jekyll serve --config _config.yml,_config_debug.ym`: Once completed the website should be available on your localhost. It runs the website from the `_site` folder. The website is updated automagically on every file change but it is not refreshed automagically. You'll need to refresh the page manually.
+- `bundle exec jekyll serve --config _config.yml,_config_debug.yml`: Once completed the website should be available on your localhost. It runs the website from the `_site` folder. The website is updated automagically on every file change but it is not refreshed automagically. You'll need to refresh the page manually.