Merge pull request #313 from hingston/fix/readme-data-and-docs

Correct the README tables, document the rules, and add a checker that keeps them correct

Author: hingston

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Steam thread
+    url: https://steamcommunity.com/app/792100/discussions/0/1739968490573286109/
+    about: Post a solution or discuss the puzzles on Steam instead.
+  - name: OCD+ challenge stat page
+    url: https://tomorrowcorporation.com/7billionhumansStats/
+    about: The shortest and fastest known solutions the tables are compared against.

.github/ISSUE_TEMPLATE/credit-correction.yml

@@ -0,0 +1,36 @@
+name: Credit correction
+description: Claim or correct the credit for a solution
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The Contributor column records who provided a solution here, which is not always who found it first.
+        Earlier discovery can be credited if it was posted somewhere public and dated.
+  - type: input
+    id: level
+    attributes:
+      label: Level
+      description: The year number and puzzle name, and whether it is the size, speed or both row.
+      placeholder: Year 50 - Cubical Communication (size)
+    validations:
+      required: true
+  - type: input
+    id: credit
+    attributes:
+      label: Who should be credited?
+      description: A name, and a link to a GitHub or Steam profile if there is one.
+    validations:
+      required: true
+  - type: input
+    id: evidence
+    attributes:
+      label: Link to the earlier posting
+      description: A dated public link — a Steam thread, forum post, video or similar.
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: For example if the solution was found independently by several people.

.github/ISSUE_TEMPLATE/paste-only-solution.yml

@@ -0,0 +1,31 @@
+name: Paste-only solution
+description: Flag a listed solution that cannot be typed into the game's editor
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Solutions that can only be entered by pasting the text in are marked 📋 in the tables.
+        The level a command becomes available at is easy to get wrong, so please say what you checked.
+  - type: input
+    id: level
+    attributes:
+      label: Level
+      description: The year number and puzzle name, and whether it is the size, speed or both row.
+      placeholder: Year 06 - Little Exterminator 1 (both)
+    validations:
+      required: true
+  - type: input
+    id: command
+    attributes:
+      label: Which command cannot be built?
+      placeholder: pickup c,s
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: How did you check?
+      description: For example which options the editor offers at that level, or where the command is first unlocked.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/solution-improvement.yml

@@ -0,0 +1,56 @@
+name: Better solution
+description: Report a solution that beats one in the tables
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        If you can open a pull request instead, please do — it is quicker and you keep the credit.
+  - type: input
+    id: level
+    attributes:
+      label: Level
+      description: The year number and puzzle name.
+      placeholder: Year 34 - Seek and Destroy 1
+    validations:
+      required: true
+  - type: dropdown
+    id: type
+    attributes:
+      label: What does it improve?
+      options:
+        - Size
+        - Speed
+        - Both
+    validations:
+      required: true
+  - type: input
+    id: scores
+    attributes:
+      label: Size and speed
+      description: The numbers the game reports when the solution finishes.
+      placeholder: 7 commands, 890 steps
+    validations:
+      required: true
+  - type: input
+    id: reliability
+    attributes:
+      label: How often does it succeed?
+      description: 99%+, 50-99% or under 50%. Say how you worked it out if it is not obvious.
+      placeholder: 99%+
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: The solution
+      description: Paste the solution exactly as the game exports it.
+      render: text
+    validations:
+      required: true
+  - type: checkboxes
+    id: pasteable
+    attributes:
+      label: Entering it
+      options:
+        - label: This solution has to be pasted in, because the editor cannot build it at that level

.github/dependabot.yml

@@ -6,4 +6,9 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "weekly"
+    groups:
+      # One pull request for all action updates rather than one per action
+      github-actions:
+        patterns:
+          - "*"

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+<!-- Thanks for contributing! Delete anything below that does not apply. -->
+
+## What is this?
+
+<!-- e.g. "Year 34 Seek and Destroy 1 (size) down to 7 commands" -->
+
+## Checklist
+
+- [ ] The file is named `Year NUM - NAME (TYPE).txt` and is in the folder that matches how often it succeeds
+- [ ] The README row is updated, with the size and speed the game reports
+- [ ] `python check_names.py` and `python check_readme.py` both pass
+- [ ] Marked 📋 if the solution has to be pasted in because the editor cannot build it at that level
+- [ ] Credited to the right person (see [CONTRIBUTING.md](../CONTRIBUTING.md))

.github/workflows/check-format.yml

@@ -1,6 +1,13 @@
 name: Check Formatting
 on:
   pull_request:
+  push:
+    branches: [master]
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 jobs:
   Formatting:
     runs-on: ubuntu-latest
@@ -13,5 +20,7 @@ jobs:
         uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Check formatting is correct
+      - name: Check file names are correct
         run: python check_names.py
+      - name: Check the README matches the solutions
+        run: python check_readme.py

.github/workflows/lint.yml

@@ -1,13 +1,20 @@
 name: Lint
 on:
   pull_request:
+  push:
+    branches: [master]
+permissions:
+  contents: read
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 jobs:
   lint:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: ["3.13"]
-        lint-type: [black, flake8]
+        lint-type: [black, flake8, mypy]
     steps:
       - uses: actions/checkout@v7.0.1
       - name: Set up Python ${{ matrix.python-version }}

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for helping collect the best 7 Billion Humans solutions! Anyone is welcome to submit an improvement, either as
+a [pull request](https://help.github.com/articles/about-pull-requests/) or on
+the [Steam thread](https://steamcommunity.com/app/792100/discussions/0/1739968490573286109/).
+
+## Submitting a solution
+
+1. Copy the solution out of the game and save it as a `.txt` file in the folder that matches how reliable it is
+   (see [Which folder](#which-folder)).
+2. Name the file `Year NUM - NAME (TYPE).txt`, where `NUM` is the two digit year, `NAME` is the puzzle's name and
+   `TYPE` is `speed`, `size` or `both`.
+3. Add or update the row in the matching README table, keeping the rows in year order.
+4. Run the checks:
+
+```bash
+python check_names.py && python check_readme.py
+```
+
+Both run automatically on every pull request.
+
+## Which folder
+
+| Folder                  | Success rate | Contents                                                                  |
+|:------------------------|:-------------|:--------------------------------------------------------------------------|
+| `Solutions99+`          | 99% or more  | The main table.                                                           |
+| `Solutions50+`          | 50% to 99%   | Solutions that beat the `Solutions99+` entry but do not always succeed.   |
+| `SolutionsLowPercent`   | under 50%    | Solutions that beat the entries above but only succeed occasionally.      |
+
+A less reliable solution is only listed if it is strictly better than the entry above it: fewer commands, or fewer
+steps. A solution that only ties is not listed, because the more reliable solution is already the better answer.
+
+## How size and speed are measured
+
+**Size** is the number of commands the game counts, which is what its editor shows. Labels (`a:`), block ends
+(`endif`, `endwhile`, `endfor`) and comments are free; every other line costs one command, including `else` and `end`,
+and a condition split over several lines still only costs one. `check_readme.py` counts this for you and fails if the
+README disagrees with the file.
+
+**Speed** is the number of steps the game reports when the solution finishes. Solutions that rely on randomness do not
+have a fixed speed, so their value is written with a `~` prefix (`~155`) for a typical run, or as a range (`10-11`)
+when it varies between a couple of values.
+
+## How solutions are ranked
+
+The size and speed the game reports are the only numbers used. Two solutions with the same reported speed are
+considered equally fast, even though one may finish a fraction of a second sooner: the game does not show that
+difference, and there is no way to record it that a contributor could check. When two solutions tie on the value being
+optimised, the one that is better in the other column wins, and if they tie in both then the existing entry stays.
+
+## Solutions that have to be pasted in
+
+Some solutions use a command the game's editor will not let you build at that level, so they can only be entered by
+pasting the text in. Those rows are marked with 📋 in the README so you can tell before you try to reproduce them.
+
+If you submit a solution that has to be pasted in, please say so in your pull request and add the marker. If you spot
+a listed solution that should be marked, open an issue or a pull request; the level a command becomes available at is
+easy to get wrong, so please say which command is not available and where you checked.
+
+## Credit
+
+The **Contributor** column records who provided the solution to this repository, which is not always the person who
+first discovered it. Many of these solutions were found independently by several people, and some were posted
+elsewhere first.
+
+If you know of an earlier public posting of a solution, open an issue with a dated link to it (a Steam thread, a
+Twitch VOD, a forum post) and the credit will be updated. Where a contributor knows their solution was not the first,
+that is noted in a comment at the top of the solution file.
+
+If you would rather be credited under a different name or link, say so in your pull request or open an issue.