.. vim: set fileencoding=utf-8:
.. -*- coding: utf-8 -*-
.. +--------------------------------------------------------------------------+
   |                                                                          |
   | Licensed under the Apache License, Version 2.0 (the "License");          |
   | you may not use this file except in compliance with the License.         |
   | You may obtain a copy of the License at                                  |
   |                                                                          |
   |     http://www.apache.org/licenses/LICENSE-2.0                           |
   |                                                                          |
   | Unless required by applicable law or agreed to in writing, software      |
   | distributed under the License is distributed on an "AS IS" BASIS,        |
   | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
   | See the License for the specific language governing permissions and      |
   | limitations under the License.                                           |
   |                                                                          |
   +--------------------------------------------------------------------------+


*******************************************************************************
003. Stable Anchor Contract for Shared Common Documentation
*******************************************************************************

Status
===============================================================================

Accepted

Context
===============================================================================

The ``documentation/common`` guides are being refactored to support shared
consumption across Python and Rust projects, and are planned to move into a
separate ``documentation-common`` repository.

These guides are referenced from templates, project documentation, and
downstream repositories using deep links to section anchors.

Generated heading slugs can change when:

* heading text changes,
* renderer slug rules differ (for example, Sphinx/MyST versus other Markdown
  toolchains),
* renderer implementations evolve.

For shared documentation, anchor stability must be treated similarly to API
stability within a major docs tag line (for example, ``docs-2``).

Decision
===============================================================================

For shared Markdown content that originates from ``documentation/common``:

* Every heading must have an explicit anchor immediately before it.
* Anchors must use ASCII lowercase kebab-case IDs.
* Intra-document and cross-document deep links must target explicit IDs, not
  renderer-generated heading slugs.

  .. code-block:: markdown

      <a id="validation-workflow"></a>
      ## Validation Workflow

* Anchor IDs are part of the public documentation contract for a docs major
  line (for example, ``docs-2``).
* Removing or renaming an existing anchor ID is a breaking change and requires
  a new docs major line (for example, ``docs-3``).
* Heading text may change without breaking compatibility as long as the anchor
  ID remains stable.

This contract is primarily a maintainer-facing policy and should be documented
in project maintenance/contribution guidance, not emphasized in consumer-facing
shared guides.

Alternatives
===============================================================================

Generated Heading IDs Only
-------------------------------------------------------------------------------

* Rely on renderer-generated slugs for all headings.
* Rejected because heading edits and renderer differences can silently break
  downstream deep links.

Hybrid Policy (Generated by Default, Explicit for Some Headings)
-------------------------------------------------------------------------------

* Use generated IDs for most headings and explicit IDs only for selected
  "stable" sections.
* Rejected due to policy ambiguity and review overhead; authors and reviewers
  must continuously judge which headings are "stable enough."

Consequences
===============================================================================

Positive Consequences
-------------------------------------------------------------------------------

* Anchor stability is explicit and enforceable across docs major lines.
* Heading text can evolve without forcing downstream link breakage.
* Cross-renderer behavior is deterministic for deep links.

Negative Consequences
-------------------------------------------------------------------------------

* Authoring overhead increases because every heading requires explicit anchor
  maintenance.
* Reviewers must check anchor changes carefully, especially during refactors.

Neutral Consequences
-------------------------------------------------------------------------------

* The policy does not require consumer-visible documentation changes; it mainly
  affects maintainers and contributors who edit shared docs sources.