mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
11 hours ago 05b72a0b75d76c304966fa561c40dd12bc5498e3
docs(ai): update AI contribution guidelines and add agent instructions

This updates AI contribution guidelines and adds agent setup files for Codex and Claude to the project. We also have some (rudimentary, in development being) skills and instructions for the work with this repository. These are NOT for sites implementing the theme, just helpers for the development of the theme.
1 files deleted
2 files modified
12 files added
4 files renamed
843 ■■■■■ changed files
.agents/instructions/scratch.instructions.md 14 ●●●●● patch | view | raw | blame | history
.agents/instructions/settings.instructions.md 7 ●●●●● patch | view | raw | blame | history
.agents/instructions/shortcodes.instructions.md 11 ●●●●● patch | view | raw | blame | history
.agents/instructions/templates.instructions.md 9 ●●●●● patch | view | raw | blame | history
.agents/instructions/testing.instructions.md 10 ●●●●● patch | view | raw | blame | history
.agents/prompts/analyse-and-fix-issue-report.prompt.md patch | view | raw | blame | history
.agents/prompts/create-test-script.prompt.md patch | view | raw | blame | history
.agents/prompts/release-notes.prompt.md patch | view | raw | blame | history
.agents/prompts/test-hugo-versions.prompt.md patch | view | raw | blame | history
.agents/references/architecture.md 21 ●●●●● patch | view | raw | blame | history
.agents/references/development.md 36 ●●●●● patch | view | raw | blame | history
.agents/references/netlify.md 5 ●●●●● patch | view | raw | blame | history
.agents/skills/ananke-hugo-compatibility-testing/SKILL.md 300 ●●●●● patch | view | raw | blame | history
.agents/skills/ananke-release-notes/SKILL.md 231 ●●●●● patch | view | raw | blame | history
.vscode/instructions/shortcodes.instructions.md 17 ●●●●● patch | view | raw | blame | history
.vscode/settings.json 6 ●●●●● patch | view | raw | blame | history
AGENTS.md 18 ●●●●● patch | view | raw | blame | history
AI_CONTRIBUTIONS.md 69 ●●●●● patch | view | raw | blame | history
CONTRIBUTING.md 89 ●●●●● patch | view | raw | blame | history
.agents/instructions/scratch.instructions.md
New file
@@ -0,0 +1,14 @@
---
title: "Scratch directory"
applyTo: "scratch/**"
description: Rules for the scratch directory, which holds temporary files only.
---
The `scratch` directory is for temporary files only. It is not part of the project.
* Files in `scratch` MUST NEVER be committed.
* Agents MUST NEVER analyse files in `scratch` unless the user explicitly asks for it.
* Agents MUST NOT run linting, checks, or any other error checks on `scratch`. Do not report or fix problems in these files.
* Agents MAY create new files in `scratch`, either on their own or when the user asks for it.
* Agents MUST NOT change existing files in `scratch` without explicit instructions from the user.
* Agents MAY delete files that they created themselves, but only after the user confirms the deletion.
.agents/instructions/settings.instructions.md
New file
@@ -0,0 +1,7 @@
---
applyTo: "layouts/**/*.html,config/**/*.toml,tests/fixtures/site/**"
---
# Settings priority
Individual settings must always follow this priority: page front matter > cascade > site-wide configuration.
.agents/instructions/shortcodes.instructions.md
New file
@@ -0,0 +1,11 @@
---
applyTo: "layouts/_shortcodes/**/*.html"
---
# Shortcode changes
* Accept both named and positional parameters; use `IsNamedParams` to distinguish them.
* Use `InnerDeindent` for inner content.
* Access page and site variables through `.Page` and `.Site` from the shortcode context.
* Follow the translation rules in `templates.instructions.md`.
* Update the separate documentation repository for new or changed shortcode features.
.agents/instructions/templates.instructions.md
New file
@@ -0,0 +1,9 @@
---
applyTo: "layouts/**/*.html"
---
# Template changes
* Put user-visible strings in `i18n/*.toml`, with English source strings in `i18n/en.toml`, and read them with `lang.Translate`.
* Preserve progressive enhancement: controls that require JavaScript must remain hidden until the script enables them.
* Read `.agents/references/architecture.md` before changing rendering, extension hooks, or asset integration.
.agents/instructions/testing.instructions.md
New file
@@ -0,0 +1,10 @@
---
applyTo: "tests/**,layouts/_shortcodes/**/*.html,config/_default/params.toml"
---
# Feature tests
* For new or changed parameters or shortcodes, add fixture content under `tests/fixtures/site/`, add a relevant Playwright spec under `tests/e2e/`, and register it in `tests/catalog.yaml`.
* Name browser tests `<feature>.spec.ts`. Include interaction, rendered output, accessibility, or no-JavaScript checks as relevant.
* Run relevant tests using `.agents/references/development.md`; see `tests/README.md` for the fixture structure.
* The coverage gate requires non-empty test lists for direct `[ananke]` keys and shortcodes. Nested parameter tables are not currently gated; do not treat this as complete behavioural coverage.
.agents/prompts/analyse-and-fix-issue-report.prompt.md
.agents/prompts/create-test-script.prompt.md
.agents/prompts/release-notes.prompt.md
.agents/prompts/test-hugo-versions.prompt.md
.agents/references/architecture.md
New file
@@ -0,0 +1,21 @@
# Theme architecture
## Rendering and extension points
`layouts/baseof.html` defines the `title`, `favicon`, `head`, `header`, `main`, and `footer` blocks. It calls hooks at `body-start`, `header-before`, `header-after`, `main-before`, `main-after`, `footer-before`, `footer-after`, and `body-end`.
`partials.Include "hook.html" (dict "hook" "<name>" "context" .)` delegates to `layouts/_partials/filter.html`. The filter renders `layouts/_partials/hooks/<name>.html` when present, with caching when `cache` or `cached` is true. Otherwise it logs the unused hook. Prefer hook partials for site extensions where an appropriate hook exists, rather than overriding core partials.
`layouts/_partials/func/hooks/collector.html` records calls; a deferred template in `baseof.html` dumps them. `[ananke.hooks]` controls `disable_messages` and `verbosity`; `func/debug-cli.html` writes build-log messages.
Helper partials in `layouts/_partials/func/` often return values instead of markup, including `IsShown`, `ShowDate`, and `GetFeaturedImage`.
## Configuration and assets
Theme options use the `[ananke]` namespace in `config/_default/params.toml`. When migrating an option into this namespace, preserve the old top-level fallback and emit an `[ananke]` deprecation warning with `fmt.Warnf`; see `custom_css` in `layouts/_partials/site-style.html`.
`site-style.html` combines Tachyons, theme CSS in `assets/ananke/css/`, generated social hover colours, and `ananke.custom_css`. It uses `css.Build`, minifies outside development, and fingerprints production output. Custom CSS entries may resolve to assets, static or external URLs, or HTML partials returning CSS. Sass/SCSS is no longer compiled. Read `DESIGN.md` before changing visual styles or tokens; the theme uses Tachyons first.
JavaScript in `layouts/_partials/site-scripts.html` provides progressive enhancement. Controls that need JavaScript stay `hidden` until the script reveals them, so pages without JavaScript have no inert controls.
Social network definitions live under `[ananke.social.networks.*]`. Sites select networks with `ananke.social.follow.networks` and `ananke.social.share.networks`. SVG icons live in `assets/ananke/socials/`.
.agents/references/development.md
New file
@@ -0,0 +1,36 @@
# Development and contribution workflow
## Source map and prerequisites
Templates, partials, and shortcodes live in `layouts/`; processed assets live in `assets/ananke/`; unchanged public files live in `static/`. Translations live in `i18n/`, content templates in `archetypes/`, and automation in `scripts/`. User documentation lives in the separate `gohugo-ananke/documentation` repository.
Use Hugo compatible with `config/_default/module.toml`. Run `npm ci` for locked dependencies or `npm install` when updating dependencies; the prepare hook installs Git hooks. The pre-commit hook runs lint-staged, configured in `lint-staged.config.ts`, including Markdown, YAML, workflow, and lockfile checks.
## Commands
* `npm run check`: linting, quickstart tests, and the feature coverage gate; browser tests run separately.
* `npm run lint`: Biome, lockfile-lint, markdownlint, and TypeScript checks.
* `npm run lint:code:fix`: Biome fixes; HTML templates, Tachyons source, and asset distribution files are excluded by `biome.json`.
* `npm run lint:markdown:fix`: Markdown fixes.
* `npm run lint:typescript`: TypeScript checks without emitting files.
* `npm test`: quickstart build and generated-HTML assertions against the local working tree.
* `npm run test:quickstart:submodule`: checks the published theme installation; it does not test local changes.
* `npm run test:coverage-gate`: feature registration checks, not percentage coverage.
* `npm run test:e2e`: Playwright browser, axe accessibility, and no-JavaScript checks. Install Chromium first with `npx playwright install chromium` if needed.
* `npx playwright test tests/e2e/copy-button.spec.ts`: run one spec; use `-g "test name"` to select a test.
* `node tests/support/prepare-site.mjs`: build the fixture against the current theme.
* `node tests/support/dev-server.mjs`: build and serve the fixture. `ANANKE_TEST_PORT` changes the default port, `4321`.
The fixture builder uses a temporary theme symlink; the quickstart harness copies the working tree into a fresh temporary Hugo site. Both include uncommitted theme changes in their default modes. Use `node scripts/test-hugo-quickstart.ts --help` for options, including `--keep-on-success` to inspect generated output.
Select checks relevant to the change. Exclude `scratch/` from searches and checks, including broad lint commands. Manually check keyboard access and visual changes where relevant. See `tests/README.md` for fixture and browser-suite details.
## Style and delivery
Follow neighbouring Hugo template and CSS conventions. Existing TypeScript uses two spaces; Biome uses space indentation. Keep Markdown paragraphs on one source line, and use descriptive filenames consistent with neighbouring files.
Use branches such as `feat/<topic>`, `fix/<topic>`, `docs/<topic>`, `chore/<topic>`, or `refactor/<topic>`. Regular pull requests target `development` for squash merging; promotion to `main` uses rebase merging. Do not introduce merge commits.
Use commit messages such as `fix(layouts): correct summary dates`. Pull requests need a summary, motivation, validation results, linked issues, and screenshots for visual changes. Complete `.github/pull_request_template.md` and update documentation for user-facing changes.
Stable releases (`npm run release`) require `main`; prereleases (`npm run release:pre`) require `development`. The release configuration commits, tags, pushes, and publishes a GitHub release. Running it requires authorisation for these actions; validation alone does not authorise publication.
.agents/references/netlify.md
New file
@@ -0,0 +1,5 @@
# Netlify rules
Fetch [https://netlify.ai](https://netlify.ai) to start deploying.
For instructions to features see [https://docs.netlify.com/llms.txt](https://docs.netlify.com/llms.txt).
.agents/skills/ananke-hugo-compatibility-testing/SKILL.md
New file
@@ -0,0 +1,300 @@
---
name: hugov-testing
description: Test an Ananke site against Hugo version progressions
---
Use these instructions when testing an Ananke-based website against multiple local Hugo binaries.
The goal is to verify that the website builds correctly across a requested Hugo version range, collect full logs per Hugo version, and compare output differences, warnings, and errors.
## Hugo executable location
Assume Hugo binaries are stored in:
`~/github.com/davidsneighbour/hugov/executables/`
The binary names follow this pattern:
```text
hugo-v0.162.1
hugo-v0.162.1-extended
```
Only use the **non-extended** Hugo binaries for these tests.
Do not use binaries ending in:
```text
-extended
```
## Version range interpretation
When the user says something like:
```text
test between 160 and 162
```
interpret it as:
```text
v0.160.0 <= version < v0.163.0
```
In other words:
* `160` means all available `v0.160.x` versions.
* `161` means all available `v0.161.x` versions.
* `162` means all available `v0.162.x` versions.
* Include every patch version found locally in that range.
* Do not invent missing versions.
* Do not download Hugo versions.
* Only test versions that exist as local non-extended binaries.
Examples:
```text
test between 160 and 162
```
should include binaries such as:
```text
hugo-v0.160.0
hugo-v0.160.1
hugo-v0.161.0
hugo-v0.162.0
hugo-v0.162.1
```
but only if they exist locally.
It must exclude:
```text
hugo-v0.160.0-extended
hugo-v0.162.1-extended
```
## Required test workflow
Run the test from the root of the Ananke website repository unless the user explicitly gives another path.
For each matching Hugo binary:
1. Resolve the absolute path of the Hugo binary.
2. Extract the semantic version from the filename.
3. Run the Hugo build command using that binary.
4. Capture stdout and stderr.
5. Store the full output in a log file.
6. Record the exit status.
7. Record warnings.
8. Record errors.
9. Compare the generated output and command output across all tested versions.
10. Summarise differences.
## Log directory
Store logs in:
```text
~/.logs/ananke-hugo-tests/
```
Create the directory if it does not exist.
Each test run should create a timestamped run directory:
```text
~/.logs/ananke-hugo-tests/YYYYMMDD-HHMMSS/
```
Inside that directory, write one log file per Hugo version.
Use filenames sorted naturally by version:
```text
hugo-v0.160.0.log
hugo-v0.160.1.log
hugo-v0.161.0.log
hugo-v0.162.1.log
```
Also create a summary file:
```text
summary.md
```
The summary file must include:
* tested repository path
* test timestamp
* requested version range
* resolved Hugo binaries
* command used per version
* exit status per version
* warning count per version
* error count per version
* output differences
* build output differences
* final judgement
## Hugo command
Use this default command unless the user requests another one:
```bash
hugo --gc --minify
```
Before each Hugo run, remove the generated output directory if it exists.
Default output directory:
```text
public/
```
This prevents stale output from one version affecting another version.
## Build output isolation
Each Hugo version must build into its own output directory so that generated files can be compared.
Use this pattern:
```text
.tmp/hugo-version-tests/v0.162.1/public/
```
Run Hugo with:
```bash
hugo --gc --minify --destination ".tmp/hugo-version-tests/v0.162.1/public"
```
Before each run, remove that version's output directory.
Do not remove unrelated folders.
## Comparison requirements
After all builds finish, compare:
1. Exit status
2. stdout and stderr
3. warnings
4. errors
5. generated file lists
6. generated file contents
The comparison must identify:
* versions that failed
* versions that passed
* warnings that appear only in specific versions
* errors that appear only in specific versions
* files generated by one version but missing in another
* files with changed contents
* relevant differences in generated HTML, CSS, JS, XML, JSON, and text files
Ignore irrelevant noise where appropriate, such as:
* timestamps generated by the build
* absolute temporary paths
* known cache paths
* ordering differences that do not change generated output
Do not hide real build differences.
## Warning and error detection
Scan logs case-insensitively for lines containing:
```text
warning
warn
error
failed
deprecated
panic
timeout
```
List matching lines grouped by Hugo version.
When warnings or errors repeat across all versions, list them once and mark them as shared.
When warnings or errors only happen in some versions, highlight the affected versions.
## Required final response format
When reporting results, use this structure:
```markdown
## Hugo version test summary
Repository: `...`
Requested range: `...`
Resolved Hugo versions:
* `v0.160.0` - passed
* `v0.160.1` - passed
* `v0.161.0` - failed
* `v0.162.1` - passed
## Issues
### Errors
* `v0.161.0`: ...
### Warnings
* Shared across all versions: ...
* `v0.162.1` only: ...
## Output differences
### File list differences
* `v0.160.0` generated `...`, but `v0.162.1` did not.
### File content differences
* `public/index.html` differs between `v0.160.0` and `v0.162.1`.
  * Difference: ...
## Logs
Logs were written to:
`~/.logs/ananke-hugo-tests/YYYYMMDD-HHMMSS/`
Summary file:
`~/.logs/ananke-hugo-tests/YYYYMMDD-HHMMSS/summary.md`
## Final judgement
...
```
## Behaviour rules
* Do not use Hugo extended binaries.
* Do not download missing Hugo versions.
* Do not assume a patch version exists.
* Do not stop after the first failing version.
* Continue testing all resolved versions.
* Always keep the full log output.
* Always compare results after all runs.
* Always list the tested Hugo binary paths.
* Always show when no matching Hugo versions were found.
* Always distinguish between command output differences and generated site output differences.
* Always use explicit version numbers in the final summary.
.agents/skills/ananke-release-notes/SKILL.md
New file
@@ -0,0 +1,231 @@
---
name: ananke-release-notes
description: Create release notes for the Ananke theme from repository changes
---
Create release notes for the next Ananke release based on the current repository state, merged pull requests, commits, changed files, and existing changelog entries.
## Goal
Write clear, user-facing release notes for the Ananke theme.
The release notes must explain:
* what changed
* what users need to update
* whether the release contains breaking changes
* which Hugo version is required
* where users can read more
* which changelog entries belong to this release
The result must be suitable for publishing as a GitHub release note, documentation page, or changelog announcement.
The release title in GitHub will create the main H1 heading. Do not output an initial `# Release Notes` heading. Start with `## Breaking changes`.
## Required output structure
Use this exact structure:
```markdown
## Breaking changes
## Further notes
## Further reading
## Requirements
## Changelog
```
Do not remove headings. If a section has no relevant content, write a short sentence stating that there are no additional notes for that section.
## Primary breaking change
The release notes must include this breaking change prominently:
```markdown
BREAKING CHANGE: Ananke is now using the latest css.Build functionality of Hugo. This means that the old SASS/SCSS pipeline is removed and you need to update your build process if you were relying on it.
```
Rewrite the wording only if it improves clarity, but keep the meaning intact.
The breaking change section must explain:
* the old SASS/SCSS pipeline has been removed
* Ananke now relies on Hugo's current `css.Build` functionality
* users with custom build scripts, asset pipelines, or theme overrides may need to update their setup
* users should check their Hugo version before upgrading
* users should review any custom SASS/SCSS overrides or imports
## Requirements
The requirements section must include:
```markdown
* Hugo v0.161+
```
If repository files indicate a more specific or newer requirement, report the conflict clearly instead of silently changing the version.
## Changelog
The changelog section must be generated from repository evidence.
First, identify the previous release tag and the new release target. If a previous release tag is not provided, use the latest reachable Git tag as the start point and `HEAD` as the end point.
Run this command from the repository root to generate the raw changelog entries:
```bash
previous_tag="${PREVIOUS_TAG:-$(git describe --tags --abbrev=0)}"
current_ref="${CURRENT_REF:-HEAD}"
repo_url="$(
  git config --get remote.origin.url |
    sed -E 's#^git@github.com:#https://github.com/#; s#\.git$##'
)"
git log "${previous_tag}..${current_ref}" \
  --date=format-local:'%Y-%m-%d %H:%M %z' \
  --pretty=format:'%H%x1f%h%x1f%s%x1f%ad%x1f%an%x1f%ae' |
  sort -r -t "$(printf '\037')" -k4,4 |
  awk -F "$(printf '\037')" -v repo_url="${repo_url}" '
    function github_user_from_email(email) {
      if (email ~ /@users\.noreply\.github\.com$/) {
        sub(/^.*\+/, "", email)
        sub(/@users\.noreply\.github\.com$/, "", email)
        return email
      }
      return ""
    }
    function escape_markdown(value) {
      gsub(/\[/, "\\[", value)
      gsub(/\]/, "\\]", value)
      return value
    }
    {
      full_hash = $1
      short_hash = $2
      title = $3
      date_time = $4
      author_name = escape_markdown($5)
      author_email = $6
      user = github_user_from_email(author_email)
      if (user != "") {
        author = "[" author_name "](https://github.com/" user ")"
      } else {
        author = author_name
      }
      printf "- [%s](%s/commit/%s) %s (%s by %s)\n", short_hash, repo_url, full_hash, title, date_time, author
    }
  '
```
The command must create one Markdown list item per commit in this format:
```markdown
* [HASH](commit-url) Title (yyyy-mm-dd HH:ii timezone by [authorname](author-profile-url))
```
Use the short commit hash as the link text and link it to the full commit URL.
Issue and pull request references in commit titles should remain in GitHub-autolinkable format, for example `#123`. Do not rewrite them into manual links unless the repository tooling provides reliable issue URLs.
Link the author name to the GitHub profile when the username can be derived reliably from a GitHub noreply email address. If no GitHub username can be derived, keep the author name as plain text.
Sort changelog entries by commit date descending.
After generating the raw commit list, review it and group or summarise items when appropriate, but preserve the raw commit list if the release note needs a complete audit trail.
Include concise bullet points grouped by type when possible:
* Breaking changes
* Features
* Fixes
* Documentation
* Internal changes
* Dependencies
* Removed or deprecated functionality
Each changelog item should be user-facing. Avoid low-level commit noise unless it affects users or maintainers.
## Further notes
Use this section to explain practical upgrade impact.
Include notes about:
* build configuration changes
* removed SASS/SCSS assumptions
* CSS processing changes
* compatibility concerns
* migration considerations
* theme customisation impact
* anything users should test after upgrading
Do not invent migration steps. If the repository does not contain enough information, add a clearly marked "Needs confirmation" bullet.
## Further reading
Add links or references to relevant documentation, for example:
* Ananke documentation pages
* Hugo `css.Build` documentation
* relevant pull requests
* relevant issues
* migration notes
* changelog files
* release comparison links
Use repository links when available. Do not invent URLs.
## Style rules
Write in clear British English.
Use direct, practical language.
Avoid marketing language.
Avoid vague phrases such as "various improvements" unless the repository evidence is also vague.
Avoid emojis.
Avoid typographic punctuation. Use plain apostrophes, quotes, hyphens, and normal punctuation.
Use Markdown only.
Use `*` for unordered list items.
Use inline code formatting for filenames, commands, config keys, function names, and Hugo features.
## Evidence rules
Base the release notes on repository evidence.
Check at least:
* recent commits
* merged pull requests
* changed files
* changelog files
* documentation updates
* configuration files
* asset pipeline files
* theme build files
* Hugo module or dependency configuration
* README or migration notes
If something is unclear, include it under a "Needs confirmation" bullet instead of guessing.
## Final output
Return only the completed release notes.
Do not include analysis, explanations, or implementation notes outside the release note document.
.vscode/instructions/shortcodes.instructions.md
File was deleted
.vscode/settings.json
@@ -11,7 +11,9 @@
      "addWords": true
    }
  ],
  "cSpell.dictionaries": ["workspace"],
  "cSpell.dictionaries": [
    "workspace"
  ],
  "cSpell.enabledFileTypes": {
    "markdown": true,
    "plaintext": true,
@@ -25,7 +27,7 @@
  "explorer.fileNesting.patterns": {
    "package.json": "package-lock.json, netlify.toml, lint-staged.config.ts, .release-it.ts, biome.json, renovate.json5, .nvmrc, lychee.toml, tsconfig.json, .coderabbit.yaml",
    "theme.toml": "go.mod, go.sum",
    "README.md": "CHANGELOG.md, LICENSE.md, CONTRIBUTING.md, RELEASES.md, DESIGN.md",
    "README.md": "CHANGELOG.md, LICENSE.md, CONTRIBUTING.md, RELEASES.md, DESIGN.md, AI_CONTRIBUTIONS.md",
    "*.ts": "$(capture).md, $(capture).test.ts, $(capture).spec.ts, $(capture).d.ts, $(capture).map, $(capture).js, $(capture).jsx, $(capture).tsx"
  },
  "window.autoDetectColorScheme": false,
AGENTS.md
New file
@@ -0,0 +1,18 @@
<!-- markdownlint-disable-next-line dnb-title-case-style -->
# Repository Guidelines
Ananke is a Hugo theme distributed as `github.com/gohugo-ananke/ananke/v2` and as a Git submodule. Theme defaults live in `config/_default/`; this repository is not a complete content site.
* Preserve unrelated changes. Understand, verify, and take responsibility for contributed material.
* Use npm and retain `package-lock.json`.
* Update `gohugo-ananke/documentation` for user-facing changes.
* Use Conventional Commits and focused branches targeting `development`. Only promotion from `development` targets `main`. Use rebase or squash merges only; keep history linear.
* Do not inspect, check, or commit `scratch/`. Read `.agents/instructions/scratch.instructions.md` before working there under explicit user instructions.
## Instruction discovery
`AGENTS.md` is the canonical entry point. Read files below `.agents/instructions/` whose `applyTo` patterns match the files involved in a task; these scoped rules form part of the canonical instructions.
* Before development, validation, local previews, pull requests, or releases, read `.agents/references/development.md` and the relevant sections of `CONTRIBUTING.md`.
* Before changing rendering, hooks, configuration behaviour, CSS processing, or social integrations, read `.agents/references/architecture.md`.
* When working on Netlify configuration, features, or deployment, read `.agents/references/netlify.md`.
AI_CONTRIBUTIONS.md
New file
@@ -0,0 +1,69 @@
# AI guidelines
This policy is informed by the AI guidelines introduced in [Node.js PR #62105](https://github.com/nodejs/node/pull/62105) and the [Human Voice policy, version 1.0.0](https://ai-policy.dev/policies/human-voice/1.0.0). It is a project-specific policy and applies to this repository.
## Core principle
**Contributions are owned by people, not tools.**
AI may be used for any part of the contribution workflow, including exploring the project, producing code or other material, and submitting contributions. However, responsibility cannot be delegated.
When you submit or assume responsibility for a contribution, it becomes your work and your responsibility. An AI tool is not an author, reviewer, source, or excuse for an incorrect change.
Every contribution must be understood, verified, and owned by the person responsible for it. That person must be able to explain what changed, how it works, and why it improves the project.
The answer to "Why is this an improvement?" must never be "I'm not sure, the AI did it."
A contribution that the responsible person does not understand or cannot defend may be closed without further review.
## Using AI for contributions
AI may assist, but it must not replace judgement, understanding, or ownership.
When using AI as part of a contribution:
* **Understand the project first.** Do not skip familiarisation with the relevant parts of the project. Treat generated analysis as a hypothesis, not a fact, and verify it against the actual repository.
* **Own everything you submit.** You are responsible for every material part of the contribution, regardless of how it was produced. Do not include something that you do not understand.
* **Do not submit blind generation.** Review generated code, tests, documentation, configuration, data, translations, images, and other material critically. Remove anything unnecessary, incorrect, or unsupported.
* **Explain the improvement.** You must be able to explain the problem, the reasoning behind the proposed solution, and why the result is appropriate for this project.
* **Keep logical commits.** Structure commits clearly and coherently. Do not place unrelated generated changes into one commit. Follow the repository's commit-message and contribution guidelines.
* **Test thoroughly.** Run the relevant automated checks and personally verify the affected behaviour where manual verification is applicable. Do not assume that an output is correct because a tool produced it.
* **Protect existing tests.** Do not remove or alter tests without understanding what they verify and why the change is necessary. Check that generated tests validate the intended behaviour rather than merely reproduce the current implementation.
* **Verify claims and sources.** Check factual claims against the repository or relevant authoritative sources. Confirm that links exist and support the statements for which they are cited. An AI response is not an authoritative source.
* **Check provenance and licensing.** Do not submit generated material if you cannot reasonably establish that you have the right to contribute it. Investigate output that appears copied, unusually specific, or inconsistent with the surrounding work.
* **Protect sensitive information.** Do not provide secrets, personal data, private repository content, security reports, or other confidential information to an external tool unless the project and the applicable service explicitly permit it.
* **Stay accountable.** If you take responsibility for a contribution, you are expected to follow through. Respond to feedback using your own judgement, iterate as necessary, and either complete or close the contribution yourself.
Automated and agent-submitted contributions are permitted. Each such contribution must have an identifiable person who assumes responsibility for it and satisfies this policy. Automation does not transfer responsibility from that person to the tool.
## Scratch directory
The `scratch` directory holds temporary files only. Linting, checks, and any other error checks MUST NOT be done on the `scratch` directory. For the full rules, see [`.agents/instructions/scratch.instructions.md`](.agents/instructions/scratch.instructions.md).
## Speak for yourself
Communication must represent your own understanding and judgement.
AI may assist with drafting, editing, spelling, grammar, or translation. However, comments, issues, pull request descriptions, commit messages, and review replies must communicate what you understand and intend to say.
When using AI for communication:
* **Use your own voice.** Check, edit, and adopt the text as your own before submitting it. Clear and imperfect human communication is preferable to polished text that does not reflect the contributor's understanding.
* **Do not outsource your judgement.** Do not ask a tool to decide what you think or to conduct a discussion on your behalf.
* **Be concise and accurate.** Generated summaries are often verbose, repetitive, or incorrect. Keep only what is necessary and verified.
* **Complete templates properly.** Provide the information requested by issue and pull request templates. A generated summary is not a substitute for actual evidence and reasoning.
* **Respond to review yourself.** Base responses on your own understanding and judgement. Do not quote an AI as an authority or use it to avoid answering a reviewer's question.
## Disclosure
Routine disclosure of AI assistance is not required. The tools used do not reduce or transfer the contributor's responsibility.
Maintainers may ask how a result was produced, checked, or verified when that information is relevant to reviewing the contribution. The responsible contributor must answer such questions accurately.
Disclosure does not excuse a failure to understand, test, verify, or take responsibility for a contribution.
## Final note
AI can help explore options, produce material, and reduce friction. It does not replace responsibility, judgement, or human communication.
If your name is on a contribution, or you have assumed responsibility for it, you must understand it, verify it, and be prepared to defend it.
CONTRIBUTING.md
@@ -1,27 +1,21 @@
# Contributing to Ananke
# Contributing to ananke
Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository.
* [Ways to Contribute](#ways-to-contribute)
* [Release Process](#release-process)
* [Before You Start](#before-you-start)
* [Reporting Bugs and Requesting Features](#reporting-bugs-and-requesting-features)
* [Branch Strategy](#branch-strategy)
* [Ways to contribute](#ways-to-contribute)
* [Release process](#release-process)
* [Before you start](#before-you-start)
* [Reporting bugs and requesting features](#reporting-bugs-and-requesting-features)
* [Branch strategy](#branch-strategy)
  * [Long-lived branches](#long-lived-branches)
  * [Branch naming](#branch-naming)
* [Pull Request Workflow](#pull-request-workflow)
* [Circumventing Git Hooks](#circumventing-git-hooks)
* [Documentation Contributions](#documentation-contributions)
* [AI Guidelines](#ai-guidelines)
  * [Terminology](#terminology)
  * [Core Principle](#core-principle)
  * [Using AI for Code Contributions](#using-ai-for-code-contributions)
  * [Using AI for Communication](#using-ai-for-communication)
  * [Final Note](#final-note)
* [Pull request workflow](#pull-request-workflow)
* [Circumventing git hooks](#circumventing-git-hooks)
* [Documentation contributions](#documentation-contributions)
* [Attribution](#attribution)
* [License](#license)
## Ways to Contribute
## Ways to contribute
* Report bugs
* Suggest enhancements
@@ -29,13 +23,13 @@
* Improve templates, styles, or assets
* Improve translations in `i18n/*.toml`
## Release Process
## Release process
The project follows a structured release workflow based on conventional commits, staging branches, and automated versioning.
For details, see [Branch Strategy](#branch-strategy).
## Before You Start
## Before you start
1. Use a compatible Hugo version (see [`config/_default/module.toml`](https://github.com/gohugo-ananke/ananke/blob/main/config/_default/module.toml) for the current state).
2. Install dependencies:
@@ -62,13 +56,13 @@
 This command is run automatically after `npm install` but you can run it manually to set up hooks in an existing clone or update changed hooks. It uses `simple-git-hooks` to install a commit hook that runs `lint-staged` for markdown files, which in turn runs linting tasks on staged files.
## Reporting Bugs and Requesting Features
## Reporting bugs and requesting features
* Open bugs in [GitHub Issues](https://github.com/gohugo-ananke/ananke/issues).
* Start feature or idea discussions in [GitHub Discussions](https://github.com/gohugo-ananke/ananke/discussions).
* Include clear reproduction steps, expected behaviour, actual behaviour, and versions (`hugo version`, OS, browser if relevant).
## Branch Strategy
## Branch strategy
```mermaid
flowchart LR
@@ -102,7 +96,7 @@
git push --force-with-lease
```
## Pull Request Workflow
## Pull request workflow
1. Fork the repository and create a focused branch.
2. Keep the change set small and cohesive (which means, DO NOT introduce multiple changes in a single PR).
@@ -121,7 +115,7 @@
* screenshots when UI/visual output changes,
* linked issues (for example: `Fixes #123`).
## Circumventing Git Hooks
## Circumventing git hooks
To prevent `git commit` and `git push` from running hooks you can use the `--no-verify` flag:
@@ -132,61 +126,12 @@
This should be used sparingly and only when you have a good reason to bypass checks. If you find yourself needing to use `--no-verify` frequently, please consider improving the hooks or contributing fixes to reduce false positives.
## Documentation Contributions
## Documentation contributions
The theme documentation lives in a separate repository at [gohugo-ananke/documentation](https://github.com/gohugo-ananke/documentation).
Please keep links relative where possible and remove stale references when updating pages.
## AI Guidelines
This section is based on a proposed guideline introduced in a pull request to Node.js ([PR #62105](https://github.com/nodejs/node/pull/62105)). This is a project-specific adaptation and applies to this repository.
### Terminology
* **AI** refers to any generative tool used to produce code or text (e.g. LLM-based systems).
* **LLM** refers specifically to large language models.
* **Tool** refers to any software used to assist development, including AI.
### Core Principle
**Contributions are made by people, not tools.**
AI is acceptable as a tool for any part of the workflow. However, responsibility cannot be delegated. Every contribution must be authored, understood, and defended by the person submitting it.
The answer to "Why is this an improvement?" must never be "I'm not sure, the AI did it."
Pull requests that contain changes the author does not fully understand or demonstrate a lack of understanding will be closed without review.
### Using AI for Code Contributions
AI may assist, but it must not replace judgement, understanding, or ownership.
When using AI as part of development:
* **Understand the codebase first.** Do not skip familiarisation with the relevant subsystem. AI frequently produces incorrect or outdated assumptions. Always verify against the actual source code in this repository.
* **Own every line you submit.** You are responsible for every change in your pull request, regardless of how it was created. PRs that contain changes the author does not fully understand will be closed without review.
* **No blind generation.** Do not generate large blocks of code and submit them without review. If you do not understand what the code does, do not include it.
* **Keep logical commits.** Structure commits in a clear and coherent way. Do not dump generated changes into a single commit. Follow the repository's commit message guidelines.
* **Test thoroughly.** AI-generated code must pass all tests and be validated manually. Never assume correctness because a tool suggested it. Do not remove or alter tests without explicit understanding and justification.
* **Edit generated output critically.** AI-generated code and comments are often verbose, redundant, or incorrect. Remove what is unnecessary or incorrect. Keep only what is necessary and accurate.
* **Stay accountable.** If you open a pull request, you are expected to follow through. Respond to feedback, iterate, and either complete or close the work yourself.
### Using AI for Communication
Communication must remain human, precise, and intentional.
* **No AI-only communication.** Do not submit comments, issue descriptions, or pull request texts that are entirely generated by AI.
* **Translations should be done using dedicated translation tools:** "English is not my first language" is not a reason to use AI to generate responses. Translate your own thoughts instead of outsourcing them.
* **Verify everything.** Any AI-assisted text must be checked for correctness before submission.
* **Complete templates properly.** Fill out pull request templates with actual information. Do not replace them with generated summaries. If you use AI to generate a PR then *prompt* your tool using the template to keep the format of the PR.
* **Reference real sources.** Link to actual code, documentation, or specifications within this repository or relevant upstream sources. Do not rely on AI statements as authority. If your AI is adding links verify they do exist. It remains your contribution and your responsibility.
* **Use tools for clarity, not substitution.** They must not replace direct, intentional communication.
### Final Note
AI is a tool. It can speed things up, help explore options, and reduce friction. It does not replace responsibility. If you submit a contribution, your name is on it. Act accordingly.
## Attribution
If you want to receive attribution for your contribution please follow the [contribution guidelines](https://allcontributors.org/en/bot/usage/) to add yourself to the list of contributors [in the Ananke theme documentation](https://github.com/gohugo-ananke/documentation/). A permanently open issue to add your contribution can be found [at the documentation repository](https://github.com/gohugo-ananke/documentation/issues/1). Read the initial message to understand how to add yourself to the list of contributors.