continuous-delivery-scripts 3.5.1__tar.gz → 4.1.0__tar.gz

continuous_delivery_scripts-4.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: continuous-delivery-scripts
+Version: 4.1.0
+Summary: Git-based CI/CD tools for releases, changelogs, SPDX SBOMs and licence reporting
+Home-page: https://github.com/ARMmbed/continuous-delivery-scripts
+Author: Arm
+Author-email: adrien.cabarbaye@arm.com
+License: Apache-2.0
+Project-URL: Documentation, https://armmbed.github.io/continuous-delivery-scripts/
+Project-URL: Source, https://github.com/ARMmbed/continuous-delivery-scripts
+Project-URL: Changelog, https://github.com/ARMmbed/continuous-delivery-scripts/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ARMmbed/continuous-delivery-scripts/issues
+Keywords: ci-cd,release-automation,semantic-versioning,changelog,spdx,sbom,openchain,third-party-ip,tpip,licence-compliance,copyright,python,git
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10,<4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools
+Requires-Dist: gitpython
+Requires-Dist: towncrier==22.12.0
+Requires-Dist: pyautoversion~=1.2.0
+Requires-Dist: pdoc3==0.11.6
+Requires-Dist: toml
+Requires-Dist: semver~=2.13.0
+Requires-Dist: python-dotenv
+Requires-Dist: twine
+Requires-Dist: boto3
+Requires-Dist: detect-secrets[gibberish]==1.5.0
+Requires-Dist: packaging
+Requires-Dist: licenseheaders<0.8.9
+Requires-Dist: spdx-tools==0.6.1
+Requires-Dist: license-expression
+Requires-Dist: wcmatch
+Requires-Dist: jellyfish
+Requires-Dist: jinja2<4,>=3
+Requires-Dist: Markdown<4,>=3.7
+Requires-Dist: dataclasses; python_version < "3.7"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<!--
+Copyright (C) 2020-2026 Arm Limited or its affiliates and Contributors. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+# Continuous Delivery Scripts
+
+![Package](https://badgen.net/badge/Package/continuous-delivery-scripts/grey)
+[![Documentation](https://badgen.net/badge/Documentation/GitHub%20Pages/blue?icon=github)](https://armmbed.github.io/continuous-delivery-scripts)
+[![PyPI](https://badgen.net/pypi/v/continuous-delivery-scripts)](https://pypi.org/project/continuous-delivery-scripts/)
+[![PyPI - Status](https://img.shields.io/pypi/status/continuous-delivery-scripts)](https://pypi.org/project/continuous-delivery-scripts/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/continuous-delivery-scripts)](https://pypi.org/project/continuous-delivery-scripts/)
+[![Downloads](https://pepy.tech/badge/continuous-delivery-scripts)](https://pepy.tech/project/continuous-delivery-scripts)
+
+[![License](https://badgen.net/pypi/license/continuous-delivery-scripts)](https://github.com/ARMmbed/continuous-delivery-scripts/blob/main/LICENSE)
+[![Compliance](https://badgen.net/badge/License%20Report/compliant/green?icon=libraries)](https://armmbed.github.io/continuous-delivery-scripts/third_party_IP_report.html)
+
+[![Build Status](https://github.com/ARMmbed/continuous-delivery-scripts/actions/workflows/ci.yml/badge.svg)](https://github.com/ARMmbed/continuous-delivery-scripts/actions/workflows/ci.yml)
+
+## Summary
+
+`continuous-delivery-scripts` provides Git-based CI/CD commands for release
+automation, semantic versioning, changelog generation, SPDX SBOMs,
+third-party IP (TPIP) and licence reports, source licence headers and secret
+checks.
+
+## Overview
+
+Originally forked from [ARMmbed/mbed-tools-ci-scripts](https://github.com/ARMmbed/mbed-tools-ci-scripts),
+the tools are written in Python but support projects in other languages through
+[plugins](./continuous_delivery_scripts/plugins). Each command handles a
+focused delivery task, from recording a change to auditing licences or tagging
+a release. The shared project delivery definition lives in one place:
+`[ProjectConfig]` in `pyproject.toml`. Every command reads those settings,
+including paths, versioning rules and the selected `PROGRAMMING_LANGUAGE`,
+regardless of the project's language or CI system. The selected plugin then
+uses appropriate ecosystem tools: for example, GoReleaser for Go releases or
+wheel and Twine for Python packages. Consult the
+[plugin guides](./continuous_delivery_scripts/plugins) for language-specific
+requirements; native build manifests and credentials may still be needed. See
+the [project configuration guide](./DEVELOPMENT.md#project-configuration) for
+the `pyproject.toml` fields required by each workflow.
+
+Run the same commands locally or in any CI system that can check out
+the project's Git repository and install the required tools. This avoids
+infrastructure lock-in: the team can decide which CI system suits its project,
+including after the delivery workflow has been defined.
+
+## Usage and documentation
+
+Start with the [common use cases](#common-use-cases) below, then follow the
+[task guides](./guides/index.md) for prerequisites, outputs and CI examples.
+The [GitHub Pages site](https://armmbed.github.io/continuous-delivery-scripts/)
+publishes those guides alongside the API reference when release documentation
+is regenerated. For individual commands and their typical developer or CI
+usage, see the [command-line tools table](#command-line-tools).
+
+To include your own Markdown guides in generated documentation, configure
+their source and published folder in `[ProjectConfig]`:
+
+```toml
+DOCUMENTATION_GUIDES_DIR = "guides"
+DOCUMENTATION_GUIDES_OUTPUT_FOLDER = "guides"
+```
+
+Add `guides/index.md` with links to the other `.md` files and run
+`cd-generate-docs`. It renders the guides to HTML alongside the API reference;
+the default published folder is `guides/`. Keep the Markdown source outside
+the documentation output, which the generator clears before each build. See
+[generating code documentation](./guides/generating-code-documentation.md).
+
+## Common use cases
+
+### Generate an SPDX SBOM and third-party IP report
+
+For a project whose language plugin provides package metadata, generate SPDX
+tag-value documents for the project and its dependencies alongside an HTML
+third-party IP / TPIP licence report. Use these as inputs to an OpenChain
+licence-compliance workflow:
+
+```bash
+mkdir -p spdx-output
+cd-generate-spdx --output-dir spdx-output
+```
+
+The destination directory must exist. Check that your plugin supports metadata
+reporting: the command can finish without producing reports when it does not.
+For SPDX documents, define `PROJECT_UUID` and `[spdx]` namespace settings in
+`pyproject.toml` as described under [SPDX document identity](./DEVELOPMENT.md#spdx-document-identity).
+See [SPDX generation](./guides/generating-an-spdx-sbom.md) and
+[TPIP reporting](./guides/third-party-ip-reporting.md) for outputs and
+prerequisites.
+
+### Automate semantic releases and changelogs
+
+Record a change as a news fragment, then preview the next release version:
+
+```bash
+cd-create-news-file "Fix dependency resolution" --type bugfix
+cd-determine-version --release-type release
+```
+
+In a configured release workflow, `cd-generate-news --release-type release`
+builds the changelog from those fragments; `cd-tag-and-release` handles Git
+tags and publication through the selected language plugin. See
+[changelog management](./guides/managing-changelogs.md) and
+[release automation](./guides/automating-releases.md).
+
+### Manage source licence and copyright headers
+
+Run `cd-license-files` to apply the configured source-file headers when the
+language plugin supports them. See the
+[licence header guide](./guides/licence-header-management.md).
+
+### Prevent secrets from leaking through Git
+
+Accidentally committing a password or API token can expose it to others and
+leave it in repository history. Keep a reviewed detect-secrets registry and
+check Git-tracked files locally or in CI before a change is merged:
+
+```bash
+cd-detect-secrets --registry-file .secrets.baseline
+```
+
+The check fails on new findings. Use `cd-record-secrets` only to record values
+the team has reviewed and accepted, rather than to hide real credentials. See
+[checking for secrets](./guides/checking-for-secrets.md) and
+[recording accepted findings](./guides/recording-secrets.md).
+
+## Releases
+
+For release notes and a history of changes of all **production** releases, please see the following:
+
+- [Changelog](./CHANGELOG.md)
+
+For all available versions, see the:
+
+- [PyPI Release History](https://pypi.org/project/continuous-delivery-scripts/#history)
+
+## Versioning
+
+The version scheme follows [PEP 440](https://peps.python.org/pep-0440/) and
+[Semantic Versioning](https://semver.org/). Production releases use:
+
+- `<major>.<minor>.<patch>`
+
+Beta releases give early access to experimental features. They may be unstable,
+and interfaces introduced in a beta release may change without notice. Beta
+releases use:
+
+- `<major>.<minor>.<patch>-beta.<pre-release-number>`
+
+## Installation
+
+It is recommended that a virtual environment such as [Pipenv](https://github.com/pypa/pipenv/blob/master/README.md) is
+used for all installations to avoid Python dependency conflicts.
+
+To install the most recent production quality release use:
+
+```
+pip install continuous-delivery-scripts
+```
+
+To install a specific release:
+
+```
+pip install continuous-delivery-scripts==<version>
+```
+
+## Command-line tools
+
+Following the [Unix tools philosophy](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/c1089.htm),
+the package installs focused command-line tools. Run them within a project
+configured by `pyproject.toml`, such as [this project](./pyproject.toml). Use
+`<command> --help` for all available options; release types are `development`,
+`beta` and `release`. The final column shows where each command is most likely
+to be used; developer checks can also be incorporated into CI. These are the
+same commands whichever CI system the team chooses.
+
+| Command | What it does | Key arguments | Typical environment |
+| --- | --- | --- | --- |
+| `cd-assert-news` | Validates a branch's news files; can add a missing file for a configured dependency-update branch. | `--current-branch` (`-b`), `--local` (`-l`) | CI; `--local` for developer checks |
+| `cd-create-news-file` | Creates a one-line news fragment in the configured news directory. | Required news text; `--type` (`-t`), `--ref-number` (`-n`) | Developer |
+| `cd-determine-version` | Calculates and prints the **project's prospective release version** without generating a changelog. | Required `--release-type` (`-t`) | Developer preview or CI |
+| `cd-generate-news` | Updates the project version and, for beta or production releases, builds the changelog from news fragments; prints the resulting version. | Required `--release-type` (`-t`) | CI release flow |
+| `cd-get-config` | Prints a project configuration value. | Either `--key` (`-k`) or `--config-variable` (`-c`) | Developer or CI |
+| `cd-tag-and-release` | Runs the release flow, including documentation, licensing summaries, Git tagging, packaging and publication through the selected [language plugin](./continuous_delivery_scripts/plugins). | Required `--release-type` (`-t`); optional `--current-branch` (`-b`) | CI release flow |
+| `cd-generate-docs` | Generates code documentation in the configured output directory (or one specified on the command line). | `--output_directory` | Developer preview or CI |
+| `cd-generate-spdx` | Generates SPDX documents and third-party licence summaries, then checks licence compliance when project metadata is available. | Required `--output-dir` (`-o`); create the directory first | CI audit; developer review also possible |
+| `cd-license-files` | Adds or updates source-file licence and copyright headers when the language plugin supports them. | `--verbose` (`-v`) | Developer or CI |
+| `cd-record-secrets` | Records accepted findings in the project's [detect-secrets](https://github.com/Yelp/detect-secrets) registry. | `--registry-file` (`-r`); defaults to the configured registry | Developer (registry maintenance) |
+| `cd-detect-secrets` | Checks Git-tracked files against that registry and fails if new secrets are found. | `--registry-file` (`-r`); defaults to the configured registry | CI; developer checks also possible |
+
+For example, `cd-create-news-file "Fix dependency resolution" --type bugfix`
+adds a news fragment. For release workflow details, see the
+[development guide](./DEVELOPMENT.md).
+
+For GitHub automation that performs authenticated clone or fetch operations, see [GitHub Token Authentication](#github-token-authentication).
+
+## GitHub Token Authentication
+
+When git operations need to retry against GitHub over HTTPS, this project now uses the credential layout `https://x-access-token:<token>@github.com/<owner>/<repo>.git`.
+
+This means the token is sent in the password position with `x-access-token` as the username, which is the format GitHub accepts for workflow-generated and other non-OAuth tokens used by automation.
+
+Older `https://<token>:x-oauth-basic@github.com/...` URLs were tied to OAuth-style credentials and could reject tokens created dynamically during CI/CD flows.
+
+## Project Structure
+
+The main parts of the repository are:
+
+- `.github` - CI and GitHub configuration files.
+- `docs/` - Generated GitHub Pages guides and API reference (rebuilt on release).
+- `guides/` - Markdown source for task-based documentation.
+- `llms.txt` - A concise map of the published documentation.
+- `continuous_delivery_scripts/` - Python source files and language plugins.
+- `news/` - Collection of news files for unreleased changes.
+- `tests/` - Unit and integration tests.
+
+## Getting Help
+
+- For interface definition and usage documentation, please see [GitHub Pages](https://armmbed.github.io/continuous-delivery-scripts).
+- For a list of known issues and possible workarounds, please see [Known Issues](./KNOWN_ISSUES.md).
+- To raise a defect or enhancement please use [GitHub Issues](https://github.com/ARMmbed/continuous-delivery-scripts/issues).
+
+## Contributing
+
+- We are committed to fostering a welcoming community, please see our
+  [Code of Conduct](./CODE_OF_CONDUCT.md) for more information.
+- For ways to contribute to the project, please see the [Contributions Guidelines](./CONTRIBUTING.md)
+- For a technical introduction into developing this package, please see the [Development Guide](./DEVELOPMENT.md)

continuous_delivery_scripts-4.1.0/README.md

@@ -0,0 +1,230 @@
+<!--
+Copyright (C) 2020-2026 Arm Limited or its affiliates and Contributors. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+# Continuous Delivery Scripts
+
+![Package](https://badgen.net/badge/Package/continuous-delivery-scripts/grey)
+[![Documentation](https://badgen.net/badge/Documentation/GitHub%20Pages/blue?icon=github)](https://armmbed.github.io/continuous-delivery-scripts)
+[![PyPI](https://badgen.net/pypi/v/continuous-delivery-scripts)](https://pypi.org/project/continuous-delivery-scripts/)
+[![PyPI - Status](https://img.shields.io/pypi/status/continuous-delivery-scripts)](https://pypi.org/project/continuous-delivery-scripts/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/continuous-delivery-scripts)](https://pypi.org/project/continuous-delivery-scripts/)
+[![Downloads](https://pepy.tech/badge/continuous-delivery-scripts)](https://pepy.tech/project/continuous-delivery-scripts)
+
+[![License](https://badgen.net/pypi/license/continuous-delivery-scripts)](https://github.com/ARMmbed/continuous-delivery-scripts/blob/main/LICENSE)
+[![Compliance](https://badgen.net/badge/License%20Report/compliant/green?icon=libraries)](https://armmbed.github.io/continuous-delivery-scripts/third_party_IP_report.html)
+
+[![Build Status](https://github.com/ARMmbed/continuous-delivery-scripts/actions/workflows/ci.yml/badge.svg)](https://github.com/ARMmbed/continuous-delivery-scripts/actions/workflows/ci.yml)
+
+## Summary
+
+`continuous-delivery-scripts` provides Git-based CI/CD commands for release
+automation, semantic versioning, changelog generation, SPDX SBOMs,
+third-party IP (TPIP) and licence reports, source licence headers and secret
+checks.
+
+## Overview
+
+Originally forked from [ARMmbed/mbed-tools-ci-scripts](https://github.com/ARMmbed/mbed-tools-ci-scripts),
+the tools are written in Python but support projects in other languages through
+[plugins](./continuous_delivery_scripts/plugins). Each command handles a
+focused delivery task, from recording a change to auditing licences or tagging
+a release. The shared project delivery definition lives in one place:
+`[ProjectConfig]` in `pyproject.toml`. Every command reads those settings,
+including paths, versioning rules and the selected `PROGRAMMING_LANGUAGE`,
+regardless of the project's language or CI system. The selected plugin then
+uses appropriate ecosystem tools: for example, GoReleaser for Go releases or
+wheel and Twine for Python packages. Consult the
+[plugin guides](./continuous_delivery_scripts/plugins) for language-specific
+requirements; native build manifests and credentials may still be needed. See
+the [project configuration guide](./DEVELOPMENT.md#project-configuration) for
+the `pyproject.toml` fields required by each workflow.
+
+Run the same commands locally or in any CI system that can check out
+the project's Git repository and install the required tools. This avoids
+infrastructure lock-in: the team can decide which CI system suits its project,
+including after the delivery workflow has been defined.
+
+## Usage and documentation
+
+Start with the [common use cases](#common-use-cases) below, then follow the
+[task guides](./guides/index.md) for prerequisites, outputs and CI examples.
+The [GitHub Pages site](https://armmbed.github.io/continuous-delivery-scripts/)
+publishes those guides alongside the API reference when release documentation
+is regenerated. For individual commands and their typical developer or CI
+usage, see the [command-line tools table](#command-line-tools).
+
+To include your own Markdown guides in generated documentation, configure
+their source and published folder in `[ProjectConfig]`:
+
+```toml
+DOCUMENTATION_GUIDES_DIR = "guides"
+DOCUMENTATION_GUIDES_OUTPUT_FOLDER = "guides"
+```
+
+Add `guides/index.md` with links to the other `.md` files and run
+`cd-generate-docs`. It renders the guides to HTML alongside the API reference;
+the default published folder is `guides/`. Keep the Markdown source outside
+the documentation output, which the generator clears before each build. See
+[generating code documentation](./guides/generating-code-documentation.md).
+
+## Common use cases
+
+### Generate an SPDX SBOM and third-party IP report
+
+For a project whose language plugin provides package metadata, generate SPDX
+tag-value documents for the project and its dependencies alongside an HTML
+third-party IP / TPIP licence report. Use these as inputs to an OpenChain
+licence-compliance workflow:
+
+```bash
+mkdir -p spdx-output
+cd-generate-spdx --output-dir spdx-output
+```
+
+The destination directory must exist. Check that your plugin supports metadata
+reporting: the command can finish without producing reports when it does not.
+For SPDX documents, define `PROJECT_UUID` and `[spdx]` namespace settings in
+`pyproject.toml` as described under [SPDX document identity](./DEVELOPMENT.md#spdx-document-identity).
+See [SPDX generation](./guides/generating-an-spdx-sbom.md) and
+[TPIP reporting](./guides/third-party-ip-reporting.md) for outputs and
+prerequisites.
+
+### Automate semantic releases and changelogs
+
+Record a change as a news fragment, then preview the next release version:
+
+```bash
+cd-create-news-file "Fix dependency resolution" --type bugfix
+cd-determine-version --release-type release
+```
+
+In a configured release workflow, `cd-generate-news --release-type release`
+builds the changelog from those fragments; `cd-tag-and-release` handles Git
+tags and publication through the selected language plugin. See
+[changelog management](./guides/managing-changelogs.md) and
+[release automation](./guides/automating-releases.md).
+
+### Manage source licence and copyright headers
+
+Run `cd-license-files` to apply the configured source-file headers when the
+language plugin supports them. See the
+[licence header guide](./guides/licence-header-management.md).
+
+### Prevent secrets from leaking through Git
+
+Accidentally committing a password or API token can expose it to others and
+leave it in repository history. Keep a reviewed detect-secrets registry and
+check Git-tracked files locally or in CI before a change is merged:
+
+```bash
+cd-detect-secrets --registry-file .secrets.baseline
+```
+
+The check fails on new findings. Use `cd-record-secrets` only to record values
+the team has reviewed and accepted, rather than to hide real credentials. See
+[checking for secrets](./guides/checking-for-secrets.md) and
+[recording accepted findings](./guides/recording-secrets.md).
+
+## Releases
+
+For release notes and a history of changes of all **production** releases, please see the following:
+
+- [Changelog](./CHANGELOG.md)
+
+For all available versions, see the:
+
+- [PyPI Release History](https://pypi.org/project/continuous-delivery-scripts/#history)
+
+## Versioning
+
+The version scheme follows [PEP 440](https://peps.python.org/pep-0440/) and
+[Semantic Versioning](https://semver.org/). Production releases use:
+
+- `<major>.<minor>.<patch>`
+
+Beta releases give early access to experimental features. They may be unstable,
+and interfaces introduced in a beta release may change without notice. Beta
+releases use:
+
+- `<major>.<minor>.<patch>-beta.<pre-release-number>`
+
+## Installation
+
+It is recommended that a virtual environment such as [Pipenv](https://github.com/pypa/pipenv/blob/master/README.md) is
+used for all installations to avoid Python dependency conflicts.
+
+To install the most recent production quality release use:
+
+```
+pip install continuous-delivery-scripts
+```
+
+To install a specific release:
+
+```
+pip install continuous-delivery-scripts==<version>
+```
+
+## Command-line tools
+
+Following the [Unix tools philosophy](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/c1089.htm),
+the package installs focused command-line tools. Run them within a project
+configured by `pyproject.toml`, such as [this project](./pyproject.toml). Use
+`<command> --help` for all available options; release types are `development`,
+`beta` and `release`. The final column shows where each command is most likely
+to be used; developer checks can also be incorporated into CI. These are the
+same commands whichever CI system the team chooses.
+
+| Command | What it does | Key arguments | Typical environment |
+| --- | --- | --- | --- |
+| `cd-assert-news` | Validates a branch's news files; can add a missing file for a configured dependency-update branch. | `--current-branch` (`-b`), `--local` (`-l`) | CI; `--local` for developer checks |
+| `cd-create-news-file` | Creates a one-line news fragment in the configured news directory. | Required news text; `--type` (`-t`), `--ref-number` (`-n`) | Developer |
+| `cd-determine-version` | Calculates and prints the **project's prospective release version** without generating a changelog. | Required `--release-type` (`-t`) | Developer preview or CI |
+| `cd-generate-news` | Updates the project version and, for beta or production releases, builds the changelog from news fragments; prints the resulting version. | Required `--release-type` (`-t`) | CI release flow |
+| `cd-get-config` | Prints a project configuration value. | Either `--key` (`-k`) or `--config-variable` (`-c`) | Developer or CI |
+| `cd-tag-and-release` | Runs the release flow, including documentation, licensing summaries, Git tagging, packaging and publication through the selected [language plugin](./continuous_delivery_scripts/plugins). | Required `--release-type` (`-t`); optional `--current-branch` (`-b`) | CI release flow |
+| `cd-generate-docs` | Generates code documentation in the configured output directory (or one specified on the command line). | `--output_directory` | Developer preview or CI |
+| `cd-generate-spdx` | Generates SPDX documents and third-party licence summaries, then checks licence compliance when project metadata is available. | Required `--output-dir` (`-o`); create the directory first | CI audit; developer review also possible |
+| `cd-license-files` | Adds or updates source-file licence and copyright headers when the language plugin supports them. | `--verbose` (`-v`) | Developer or CI |
+| `cd-record-secrets` | Records accepted findings in the project's [detect-secrets](https://github.com/Yelp/detect-secrets) registry. | `--registry-file` (`-r`); defaults to the configured registry | Developer (registry maintenance) |
+| `cd-detect-secrets` | Checks Git-tracked files against that registry and fails if new secrets are found. | `--registry-file` (`-r`); defaults to the configured registry | CI; developer checks also possible |
+
+For example, `cd-create-news-file "Fix dependency resolution" --type bugfix`
+adds a news fragment. For release workflow details, see the
+[development guide](./DEVELOPMENT.md).
+
+For GitHub automation that performs authenticated clone or fetch operations, see [GitHub Token Authentication](#github-token-authentication).
+
+## GitHub Token Authentication
+
+When git operations need to retry against GitHub over HTTPS, this project now uses the credential layout `https://x-access-token:<token>@github.com/<owner>/<repo>.git`.
+
+This means the token is sent in the password position with `x-access-token` as the username, which is the format GitHub accepts for workflow-generated and other non-OAuth tokens used by automation.
+
+Older `https://<token>:x-oauth-basic@github.com/...` URLs were tied to OAuth-style credentials and could reject tokens created dynamically during CI/CD flows.
+
+## Project Structure
+
+The main parts of the repository are:
+
+- `.github` - CI and GitHub configuration files.
+- `docs/` - Generated GitHub Pages guides and API reference (rebuilt on release).
+- `guides/` - Markdown source for task-based documentation.
+- `llms.txt` - A concise map of the published documentation.
+- `continuous_delivery_scripts/` - Python source files and language plugins.
+- `news/` - Collection of news files for unreleased changes.
+- `tests/` - Unit and integration tests.
+
+## Getting Help
+
+- For interface definition and usage documentation, please see [GitHub Pages](https://armmbed.github.io/continuous-delivery-scripts).
+- For a list of known issues and possible workarounds, please see [Known Issues](./KNOWN_ISSUES.md).
+- To raise a defect or enhancement please use [GitHub Issues](https://github.com/ARMmbed/continuous-delivery-scripts/issues).
+
+## Contributing
+
+- We are committed to fostering a welcoming community, please see our
+  [Code of Conduct](./CODE_OF_CONDUCT.md) for more information.
+- For ways to contribute to the project, please see the [Contributions Guidelines](./CONTRIBUTING.md)
+- For a technical introduction into developing this package, please see the [Development Guide](./DEVELOPMENT.md)

{continuous_delivery_scripts-3.5.1 → continuous_delivery_scripts-4.1.0}/continuous_delivery_scripts/_version.py

@@ -11,8 +11,8 @@ References
 This file is autogenerated, do not modify by hand.
 """
 
-__version__ = "3.5.1"
-COMMIT = "5f0dc45967d1e56a6e03168c0c9b54cc7aaa98c7"
-MAJOR = 3
-MINOR = 5
-PATCH = 1
+__version__ = "4.1.0"
+COMMIT = "298fb1cfdf2636976e5ea78d65207793279edcca"
+MAJOR = 4
+MINOR = 1
+PATCH = 0

{continuous_delivery_scripts-3.5.1 → continuous_delivery_scripts-4.1.0}/continuous_delivery_scripts/assert_news.py

@@ -9,7 +9,7 @@ import logging
 import pathlib
 import re
 import sys
-from typing import Union, Optional, Iterable, Any, List
+from typing import Union, Optional, Iterable, Any, List, ContextManager
 
 from continuous_delivery_scripts.utils.configuration import configuration, ConfigurationVariable
 from continuous_delivery_scripts.utils.git_helpers import ProjectTempClone, LocalProjectRepository, GitWrapper
@@ -21,6 +21,10 @@ logger = logging.getLogger(__name__)
 NEWS_FILE_NAME_REGEX = r"^[0-9]+.(misc|doc|removal|bugfix|feature|major)$"
 
 
+class MissingNewsFileError(FileNotFoundError):
+    """The branch contains no added news file."""
+
+
 class NewsFileValidator:
     """Verifies individual news files."""
 
@@ -77,10 +81,11 @@ def find_news_files(git: GitWrapper, root_dir: str, news_dir: str) -> List[str]:
     # If no news files were added, then we check for addition on the branch.
     # Relies on the fact GitWrapper returns paths that are always relative
     # to the project root.
-    added_news_files = [file_path for file_path in files_changed if file_path.startswith(news_dir)]
+    news_prefix = news_dir.replace("\\", "/").rstrip("/") + "/"
+    added_news_files = [file_path for file_path in files_changed if file_path.startswith(news_prefix)]
     if len(added_news_files) == 0:
         files_changed = git.list_files_added_on_current_branch()
-        added_news_files = [file_path for file_path in files_changed if file_path.startswith(news_dir)]
+        added_news_files = [file_path for file_path in files_changed if file_path.startswith(news_prefix)]
     return [str(pathlib.Path(root_dir, file_path)) for file_path in added_news_files]
 
 
@@ -94,7 +99,7 @@ def validate_news_files(git: GitWrapper, root_dir: str, news_dir: str) -> None:
     """
     added_news_files = find_news_files(git=git, news_dir=news_dir, root_dir=root_dir)
     if not added_news_files:
-        raise FileNotFoundError(f"PR must contain a news file in {news_dir}. See README.md.")
+        raise MissingNewsFileError(f"PR must contain a news file in {news_dir}. See README.md.")
     for absolute_file_path in added_news_files:
         validate_news_file(absolute_file_path)
 
@@ -154,18 +159,19 @@ def main() -> None:
     args = parser.parse_args()
     set_log_level(args.verbose)
 
-    with (
-        LocalProjectRepository()  # type: ignore
-        if args.local
-        else ProjectTempClone(desired_branch_name=args.current_branch)
-    ) as git:
+    repository: ContextManager[GitWrapper]
+    if args.local:
+        repository = LocalProjectRepository()
+    else:
+        repository = ProjectTempClone(desired_branch_name=args.current_branch)
+    with repository as git:
         if git.is_current_branch_feature():
             root_dir = configuration.get_value(ConfigurationVariable.PROJECT_ROOT)
             absolute_news_dir = configuration.get_value(ConfigurationVariable.NEWS_DIR)
             news_dir = str(pathlib.Path(absolute_news_dir).relative_to(root_dir))
             try:
-                validate_news_files(git=git, news_dir=news_dir, root_dir=root_dir)
-            except Exception as e:
+                validate_news_files(git=git, news_dir=news_dir, root_dir=str(git.root))
+            except MissingNewsFileError as e:
                 log_exception(logger, e)
                 try:
                     news_file = generate_news_file(git, git.get_corresponding_path(pathlib.Path(news_dir)))
@@ -173,6 +179,9 @@ def main() -> None:
                 except Exception as e2:
                     log_exception(logger, e2)
                 sys.exit(1)
+            except Exception as e:
+                log_exception(logger, e)
+                sys.exit(1)
 
 
 if __name__ == "__main__":