diff --git a/.github/workflows/auto-draft-pr.yaml b/.github/workflows/auto-draft-pr.yaml index 2de9158a170..e7016bb9657 100644 --- a/.github/workflows/auto-draft-pr.yaml +++ b/.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 }} diff --git a/changelog/snippets/sections/template-snippet.md b/changelog/snippets/sections/template-snippet.md new file mode 100644 index 00000000000..cb16971c9d5 --- /dev/null +++ b/changelog/snippets/sections/template-snippet.md @@ -0,0 +1 @@ +- Your explanation here (#XYZW). diff --git a/docs/Gemfile b/docs/Gemfile index 0a1bfe62ac8..d9afbf0c4f2 100644 --- a/docs/Gemfile +++ b/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" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index dce74203b81..f3e573a950d 100644 --- a/docs/Gemfile.lock +++ b/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) diff --git a/docs/_plugins/balance_change.rb b/docs/_plugins/balance_change.rb new file mode 100644 index 00000000000..f79f63630d7 --- /dev/null +++ b/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*-->\s*([^<\s]+)/, + '\1 → \2' + ) + +end \ No newline at end of file diff --git a/docs/_plugins/unit_block.rb b/docs/_plugins/unit_block.rb new file mode 100644 index 00000000000..f4c5b81d339 --- /dev/null +++ b/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 +
+ + #{name} +
+ HTML + end + end +end + +Liquid::Template.register_tag('unit', Jekyll::UnitBlock) \ No newline at end of file diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss new file mode 100644 index 00000000000..3c8d05b05b0 --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/docs/assets/icons/XES0102.png b/docs/assets/icons/XES0102.png new file mode 100644 index 00000000000..68d1571cbe7 Binary files /dev/null and b/docs/assets/icons/XES0102.png differ diff --git a/docs/development-changelog.md b/docs/development-changelog.md index 4a2cf570923..8e47ffaf6da 100644 --- a/docs/development-changelog.md +++ b/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, ...) `. 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: diff --git a/docs/development-changelog/balance-snippet.md b/docs/development-changelog/balance-snippet.md index c915d2872a2..0a5ce5996c6 100644 --- a/docs/development-changelog/balance-snippet.md +++ b/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..md`. ``` -- (#) - - ** ():** - -
- - : --> - - : --> +{% unit %} + +{% endunit %} + (#) +- : + - : --> ``` - 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: `: ` 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: `: ` 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: ` () --> ()`. + +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 diff --git a/docs/development-changelog/other-snippet.md b/docs/development-changelog/other-snippet.md index a1a2bd00a02..31d644d2834 100644 --- a/docs/development-changelog/other-snippet.md +++ b/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). + +``` diff --git a/docs/documentation.md b/docs/documentation.md index c6a0a215132..c465f2b66a0 100644 --- a/docs/documentation.md +++ b/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.