From ffccdec2b48cbba38d2cdbaf0d492878e46cb561 Mon Sep 17 00:00:00 2001 From: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com> Date: Tue, 17 Nov 2026 11:50:46 +0000 Subject: [PATCH] docs(ai): update ai documentation --- AI_GUIDELINE.md | 65 +++++++++++++++++++++ CONTRIBUTING.md | 89 +++++------------------------ 2 files changed, 82 insertions(+), 72 deletions(-) diff --git a/AI_GUIDELINE.md b/AI_GUIDELINE.md new file mode 100644 index 0000000..caf6e05 --- /dev/null +++ b/AI_GUIDELINE.md @@ -0,0 +1,65 @@ +# 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. + +## 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 361b32d..f5a7ed7 100644 --- a/CONTRIBUTING.md +++ b/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. -- Gitblit v1.10.0