@@ -20,6 +20,45 @@ Feature management provides a way to develop and expose application functionalit
2020
2121## Contributing
2222
23+ ### Release documentation
24+
25+ The [ release documentation workflow] ( https://github.com/microsoft/FeatureManagement-Python/actions/workflows/docs.yml )
26+ builds the verified ` v2.2.0 ` source, not the current ` main ` API.
27+ The initial release is selected once through the workflow's ` RELEASE_TAG ` setting.
28+ The builder resolves that tag's commit, derives its version, and checks that the imported package version agrees;
29+ it contains no release-specific version or commit constants.
30+ Pull requests and relevant changes merged into ` main ` build and validate the site without deploying it.
31+ The downloadable ` github-pages ` artifact contains the complete site, including ` /2.2.0/ ` , ` /latest/ ` ,
32+ and redirects for existing ` /html/ ` links.
33+
34+ To build locally on Windows, use a separate release checkout and virtual environment:
35+
36+ ``` powershell
37+ git worktree add --detach ..\FeatureManagement-Python-2.2.0 v2.2.0
38+ py -3.14 -m venv ..\FeatureManagement-Python-2.2.0\.venv
39+ & ..\FeatureManagement-Python-2.2.0\.venv\Scripts\Activate.ps1
40+ python -m pip install -r docs\requirements.txt ..\FeatureManagement-Python-2.2.0
41+ python scripts\build_release_docs.py --source ..\FeatureManagement-Python-2.2.0 --tag v2.2.0
42+ Start-Process docs\_build\site\index.html
43+ ```
44+
45+ Reuse an existing clean release checkout instead of adding it again.
46+ The builder rejects the wrong commit or tracked release edits, validates local links and API anchors,
47+ and replaces the local site only after a successful build. Generated pages are not committed.
48+ Required API anchors come from methods declared by the tagged feature managers, not a version-independent API list.
49+ Only stable release tags can become ` /latest/ ` ; prerelease and development tags are rejected.
50+ Rendering fixes apply only during the build; the historical library source remains unchanged.
51+ SDK documentation follows the [ Azure SDK Python Design Guidelines] ( https://azure.github.io/azure-sdk/python_design.html ) .
52+
53+ Deployment is opt-in. After merging this workflow and configuring Pages to use ** GitHub Actions** , allow ` main `
54+ in the ` github-pages ` environment. Run ** Release documentation** manually from ` main ` and enable its ` deploy ` input.
55+ No new secret is required, and PR builds never receive Pages deployment permissions.
56+ Keep ` gh-pages ` unchanged as a fallback; rollback consists of restoring its ` /docs ` folder as the Pages source
57+ and allowing ` gh-pages ` in the deployment environment.
58+
59+ The bootstrap site contains one configured release. Retaining multiple versions, validating older documentation
60+ builds, and registration of future releases are separate follow-up work.
61+
2362This project welcomes contributions and suggestions. Most contributions require you to agree to a
2463Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
2564the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com .
0 commit comments