Add towncrier, update CONTRIBUTING, update workflow and skip CI when not needed - #464

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
count=$(rg -c '^permissions:' .github/workflows/ci.yml || true)
test "$count" -eq 1
rg -n -A2 '^permissions:' .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 203

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- workflow ---'
cat -n .github/workflows/ci.yml

printf '%s\n' '--- permissions and action usage ---'
rg -n -C2 'permissions:|dorny/paths-filter|actions/checkout|pull_request_target|pull_request:' .github/workflows .github/actions 2>/dev/null || true

printf '%s\n' '--- repository workflow files ---'
git ls-files '.github/workflows/*' '.github/actions/*'

Repository: cpplint/cpplint

Length of output: 5803

🌐 Web query:

dorny paths-filter v4 pull_request permissions contents read pull-requests read documentation

💡 Result:

When using the dorny/paths-filter action (version 4) in workflows triggered by pull_request or pull_request_target events, the action requires the pull-requests: read permission to use the GitHub REST API for detecting changes against the base branch [1][2][3]. In most common workflow configurations, you should include both pull-requests: read (for the action) and contents: read (typically required by actions/checkout) in your job's permissions block [1][4][5]: permissions: contents: read pull-requests: read If these permissions are not explicitly defined at the job or workflow level, the action may fail with a "Resource not accessible by integration" error because the default token permissions might be insufficient [4][6].

Citations:

• 1: https://github.com/dorny/paths-filter/blob/master/README.md
• 2: https://github.com/dorny/paths-filter
• 3: https://context7.com/dorny/paths-filter/llms.txt
• 4: remote: Repository not found dorny/paths-filter#243
• 5: https://github.com/marketplace/actions/paths-changes-filter
• 6: Error: Resource not accessible by integration dorny/paths-filter#270

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
rg -n 'types:.*unlabeled' .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 153

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- workflow ---'
cat -n .github/workflows/ci.yml
printf '%s\n' '--- label references ---'
rg -n -C 3 'skip-changelog|unlabeled|labeled|pull_request' .github/workflows README.md .github 2>/dev/null || true

Repository: cpplint/cpplint

Length of output: 7737

🌐 Web query:

GitHub Actions pull_request unlabeled activity type workflow trigger documentation

💡 Result:

To trigger a GitHub Actions workflow when a label is added to or removed from a pull request, you must use the pull_request event with the labeled or unlabeled activity types [1][2]. By default, a pull_request workflow only triggers on the opened, synchronize, and reopened activity types [1][3]. To include labeled or unlabeled activity, you must explicitly define these using the types keyword in your workflow configuration [1][2]. Example configuration: on: pull_request: types: - opened - synchronize - reopened - labeled - unlabeled When you use the types keyword, you must explicitly list all the activity types you want to trigger the workflow, including the default ones if you still want the workflow to run for those events [1][2]. Important Considerations: - If you specify multiple activity types, the workflow will trigger whenever any one of them occurs [4][5]. - You can access information about the event, such as which label was added or removed, using the GitHub Actions context, specifically github.event [6]. - Note that other activity types, such as labeled and unlabeled, do not automatically create workflow runs in an approval-required state (unlike opened, synchronize, and reopened which might trigger security checks if automated) [3][4]. For further details, consult the official GitHub documentation on events that trigger workflows [1][2] and workflow syntax [5].

Citations:

• 1: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
• 2: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
• 3: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow
• 4: https://docs.github.com/actions/using-workflows/triggering-a-workflow
• 5: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions
• 6: Run action on labeled, unlabeled rossjrw/pr-preview-action#91

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
grep -Fq "if: needs.choose-jobs.outputs.shouldTest == 'true'" .github/workflows/ci.yml
grep -Fq "needs.choose-jobs.outputs.needsLog == 'true'" .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 153

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- workflow excerpt ---'
cat -n .github/workflows/ci.yml | sed -n '1,100p'

printf '%s\n' '--- condition references ---'
rg -n -C 3 "shouldTest|needsLog|choose-jobs|build-test|pass:" .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 5737

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
cat -n .github/workflows/ci.yml | sed -n '1,100p'

Repository: cpplint/cpplint

Length of output: 3650

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
import re

text = Path(".github/workflows/ci.yml").read_text()

required = {
    "shouldTest output": r"shouldTest:\s*\$\{\{\s*steps\.filter\.outputs\.nondoc\s*==\s*'true'\s*\}\}",
    "needsLog output": r"needsLog:\s*\$\{\{\s*steps\.filter\.outputs\.py\s*==\s*'true'\s*\}\}",
    "build-test gate": r"if:\s*needs\.choose-jobs\.outputs\.shouldTest\b(?!\s*==)",
    "changelog gate": r"needs\.choose-jobs\.outputs\.needsLog\s*&&",
}

for name, pattern in required.items():
    print(f"{name}: {'present' if re.search(pattern, text) else 'absent'}")

# Job outputs are string-valued at the needs.*.outputs boundary.
for value in ("true", "false"):
    print(f"needs output {value!r}: {'runs' if bool(value) else 'skips'} under non-empty-string truthiness")
PY

Repository: cpplint/cpplint

Length of output: 375

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
import re

text = Path(".github/workflows/ci.yml").read_text()

checks = {
    "shouldTest output": r"shouldTest:\s*\$\{\{\s*steps\.filter\.outputs\.nondoc\s*==\s*'true'\s*\}\}",
    "needsLog output": r"needsLog:\s*\$\{\{\s*steps\.filter\.outputs\.py\s*==\s*'true'\s*\}\}",
    "build-test direct gate": r"if:\s*needs\.choose-jobs\.outputs\.shouldTest\s*$",
    "changelog direct gate": r"needs\.choose-jobs\.outputs\.needsLog\s*&&",
}

for name, pattern in checks.items():
    print(f"{name}: {'present' if re.search(pattern, text, re.MULTILINE) else 'absent'}")

for value in ("true", "false"):
    print(f"{value!r} is non-empty: {bool(value)}")
PY

Repository: cpplint/cpplint

Length of output: 321

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
! rg -nF 'github.event.pull_request.user.name' .github/workflows/ci.yml
rg -nF 'github.event.pull_request.user.login' .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 217

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- workflow context ---'
sed -n '45,75p' .github/workflows/ci.yml

printf '%s\n' '--- pre-commit identity references ---'
rg -n -i 'pre-commit-ci|user\.(name|login)' .github README.md pyproject.toml setup.cfg 2>/dev/null || true

Repository: cpplint/cpplint

Length of output: 1444

🌐 Web query:

GitHub pre-commit.ci pull request author event pull_request user.login exact value

💡 Result:

The exact value for the pull request author (user login) associated with the pre-commit.ci bot is 'pre-commit-ci[bot]' [1][2][3]. When creating automated workflows in GitHub Actions to filter or identify pull requests created by pre-commit.ci, you can use this identifier within your conditional logic [1][2][3]. For example, to check the author of a pull request in a GitHub Actions workflow step, you would use: ${{ github.event.pull_request.user.login == 'pre-commit-ci[bot]' }} [1][2] This identifier is consistent with GitHub's naming convention for official integration bots [4]. Note that pre-commit.ci operates as an app, and its automated pull requests (such as autoupdates) will appear with this username [5][4].

Citations:

• 1: https://github.com/ansys/grantami-bomanalytics/blob/main/.github/workflows/dependabot_approve.yml
• 2: [BUG]: Ignore comment placement is not intuitive zizmorcore/zizmor#612
• 3: https://github.com/EleutherAI/bergson/blob/main/.github/workflows/claude-code-review.yml
• 4: [pre-commit.ci] pre-commit autoupdate MrThearMan/django-post-fetch-hook#262
• 5: https://pre-commit.ci/

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
grep -Fq 'needs: [ choose-jobs, build-test, changelog ]' .github/workflows/ci.yml
grep -Fq 'needs.choose-jobs.result' .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 153

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- workflow structure ---'
nl -ba .github/workflows/ci.yml | sed -n '1,120p'

printf '%s\n' '--- job identifiers and dependencies ---'
rg -n '^[[:space:]]{2}[A-Za-z0-9_-]+:|^[[:space:]]{4}(needs|if|runs-on):|needs\.[A-Za-z0-9_-]+\.result' .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 220

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
import re

text = Path(".github/workflows/ci.yml").read_text()
jobs = re.search(r"(?ms)^jobs:\n(.*?)(?=^ [A-Za-z]|\Z)", text)
print("jobs section found:", bool(jobs))
for name in ("choose-jobs", "build-test", "changelog", "pass"):
    m = re.search(rf"(?ms)^  {re.escape(name)}:\n(.*?)(?=^  [A-Za-z0-9_-]+:|\Z)", text)
    print(f"\n[{name}]")
    print(m.group(0) if m else "missing")
PY

Repository: cpplint/cpplint

Length of output: 2948

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
import re

text = Path(".github/workflows/ci.yml").read_text()
for name in ("choose-jobs", "build-test", "changelog", "pass"):
    start = re.search(rf"(?m)^  {re.escape(name)}:", text)
    if not start:
        print(f"{name}: missing")
        continue
    end = re.search(r"(?m)^  [A-Za-z0-9_-]+:", text[start.end():])
    block = text[start.start(): start.end() + (end.start() if end else len(text))]
    print(f"\n--- {name} ---")
    print(block)
PY

Repository: cpplint/cpplint

Length of output: 2947

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
if rg -n 'echo .*`skip-changelog`' .github/workflows/ci.yml; then
  exit 1
fi
rg -n 'printf|GITHUB_STEP_SUMMARY' .github/workflows/ci.yml

Repository: cpplint/cpplint

Length of output: 443

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- workflow context ---'
cat -n .github/workflows/ci.yml | sed -n '68,83p'

printf '%s\n' '--- documentation references ---'
rg -n 'CONTRIBUTING\.rst#(pull-requests|testing)|crytown|develop' .github README.md CONTRIBUTING.rst 2>/dev/null || true

printf '%s\n' '--- isolated Bash behavior ---'
tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT
bash -c 'echo "Please follow instructions\nor request the `skip-changelog` label." >> "$1"' bash "$tmp" 2>"$tmp.stderr" || true
printf '%s\n' 'output bytes:'
od -An -t x1c "$tmp"
printf '%s\n' 'stderr:'
cat "$tmp.stderr"
printf '%s\n' 'printf output bytes:'
bash -c 'printf "%s\n" "Please follow instructions" "Or request the \`skip-changelog\` label."' bash | od -An -t x1c

Repository: cpplint/cpplint

Length of output: 2071

🏁 Script executed:

#!/usr/bin/env bash
set -u

out="$(mktemp)"
err="$(mktemp)"
trap 'rm -f "$out" "$err"' EXIT

bash -c 'echo "Please follow instructions\nor request the `skip-changelog` label."' bash \
  >"$out" 2>"$err" || printf 'shell status: %s\n' "$?"

python3 - "$out" "$err" <<'PY'
import pathlib
import sys

for label, path in (("stdout", sys.argv[1]), ("stderr", sys.argv[2])):
    data = pathlib.Path(path).read_bytes()
    print(f"{label} bytes: {data!r}")
PY

printf '%s\n' '--- URL status ---'
for url in \
  'https://github.com/cpplint/cpplint/blob/crytown/CONTRIBUTING.rst#pull-requests' \
  'https://github.com/cpplint/cpplint/blob/develop/CONTRIBUTING.rst#pull-requests' \
  'https://github.com/cpplint/cpplint/blob/develop/CONTRIBUTING.rst#testing'
do
  curl -L -sS -o /dev/null -w '%{http_code} %{url_effective}\n' "$url" || true
done

Repository: cpplint/cpplint

Length of output: 553

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- CONTRIBUTING.rst ---'
sed -n '45,105p' CONTRIBUTING.rst

printf '%s\n' '--- pyproject.toml ---'
sed -n '1,45p' pyproject.toml

printf '%s\n' '--- tox.ini ---'
cat -n tox.ini

printf '%s\n' '--- relevant references ---'
rg -n -C 3 'pre-commit|tox -e|py39|py310|py313|pypy3|towncrier|changelog|no changelog|no[- ]?news' CONTRIBUTING.rst pyproject.toml tox.ini .github 2>/dev/null || true

Repository: cpplint/cpplint

Length of output: 13234

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- CI workflow ---'
cat -n .github/workflows/ci.yml | sed -n '1,85p'

printf '%s\n' '--- changelog-related repository configuration ---'
rg -n -C 5 'skip-changelog|changes/|hasLog|nondoc|paths-filter|changelog' .github CONTRIBUTING.rst pyproject.toml

printf '%s\n' '--- deterministic configuration check ---'
python3 - <<'PY'
from pathlib import Path
import re

project = Path("pyproject.toml").read_text()
tox = Path("tox.ini").read_text()
contributing = Path("CONTRIBUTING.rst").read_text()

requires = re.search(r'requires-python\s*=\s*"([^"]+)"', project)
envlist = re.search(r'^envlist\s*=\s*(.+)$', tox, re.MULTILINE)
commands = tox.split("[testenv]", 1)[1].split("commands =", 1)[1].strip().splitlines()
examples = re.findall(r'`tox -e ([^`]+)`', contributing)

print("requires-python:", requires.group(1) if requires else None)
print("tox envlist:", envlist.group(1).strip() if envlist else None)
print("tox commands:", [line.strip() for line in commands if line.strip()])
print("documented tox examples:", examples)
print("py39 below minimum:", "py39" in examples and ">=3.10" in project)
print("pre-commit in tox commands:", any("pre-commit" in line for line in commands))
PY

Repository: cpplint/cpplint

Length of output: 11519

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
rg -nF 'package = "cpplint"' pyproject.toml
for kind in breaking feature bugfix refactor; do
  rg -nF "directory = \"$kind\"" pyproject.toml
done

Repository: cpplint/cpplint

Length of output: 153

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- pyproject.toml Towncrier and dependencies ---'
rg -n -C 8 'towncrier|\[tool\.towncrier\]|\[project\]|\[build-system\]|dependencies|cpplint' pyproject.toml
printf '%s\n' '--- release instructions ---'
rg -n -C 12 'towncrier|__VERSION__|release|changelog' CONTRIBUTING.rst README.rst README.md 2>/dev/null || true
printf '%s\n' '--- version declarations ---'
rg -n -C 3 '__VERSION__|version\s*=' --glob '*.py' --glob 'pyproject.toml' --glob 'setup.cfg' --glob 'setup.py'
printf '%s\n' '--- repository Towncrier fragments ---'
git ls-files 'changes/**' | head -80

Repository: cpplint/cpplint

Length of output: 9596

🌐 Web query:

Towncrier 24.7.0 configuration directory type package default documentation

💡 Result:

In Towncrier 24.7.0, the configuration is managed within either a pyproject.toml or towncrier.toml file under the [tool.towncrier] namespace [1][2]. If both files exist, towncrier.toml takes precedence [3]. Regarding the directory where news fragments are stored: 1. Default Behavior for Python Projects: If you specify the package key in your configuration, Towncrier defaults to looking for a directory named newsfragments located within that package [1]. 2. Default Behavior for Non-Python Projects (or if package is not set): The default is a newsfragments directory relative to either the directory specified by the --dir command-line option or, by default, the directory containing the configuration file [1][3]. 3. Explicit Configuration: You can explicitly set the directory key under [tool.towncrier] to override these defaults [1]. For custom fragment types, you can define them using an array of tables in your configuration file under [[tool.towncrier.type]] [1]. Each type requires a directory key, which specifies the sub-directory name for that fragment type (e.g., "feature", "bugfix") [1][4]. When the top-level directory is set, these section paths are appended to it; otherwise, "newsfragments" is typically added to the end of each path [1].

Citations:

• 1: https://towncrier.readthedocs.io/en/24.7.0/configuration.html
• 2: https://towncrier.readthedocs.io/en/24.7.0/tutorial.html
• 3: https://towncrier.readthedocs.io/en/24.7.0/cli.html
• 4: https://towncrier.readthedocs.io/en/23.11.0/configuration.html

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
python3 - <<'PY'
from urllib.request import urlopen
from html import unescape
import re

url = "https://towncrier.readthedocs.io/en/24.7.0/configuration.html"
html = urlopen(url, timeout=10).read().decode()
text = unescape(re.sub(r"<[^>]+>", " ", html))
text = re.sub(r"\s+", " ", text)
for term in ("package", "directory", "type"):
    print(f"--- {term} ---")
    for match in re.finditer(term, text, re.IGNORECASE):
        print(text[max(0, match.start()-220):match.start()+500])
PY

Repository: cpplint/cpplint

Length of output: 2439

🌐 Web query:

Towncrier configuration package omitted version discovery pyproject.toml package key

💡 Result:

In Towncrier, the package key in your pyproject.toml (under the [tool.towncrier] section) is used to specify the Python package name, which enables Towncrier to automatically discover your project's version and name [1][2]. When you provide the package key, Towncrier attempts to determine the version using the following mechanisms in order of precedence: 1. Manual Override: Explicitly passing the --version argument via the command line takes highest precedence [2][3]. 2. Configuration File: Setting the version key directly within the [tool.towncrier] section of your pyproject.toml file takes next precedence [2][3]. 3. Automatic Discovery: If no version is explicitly provided via the above methods, Towncrier will attempt to resolve the version using the package specified in the package key [1][2]. It looks for: * Metadata: The installed package's metadata (if the package is installed) [2][3]. * Source Code: A version variable defined in the top-level package, which can be a string literal, a tuple, or an Incremental version object [2][3]. If the package key is omitted or Towncrier is unable to automatically determine the version through these methods, you must provide the version explicitly using the command line flag --version during the build process [1][4]. Note that while recent developments have allowed for more flexible configuration, if you encounter issues with version discovery, ensuring your package is installed in your environment or that a version string is correctly defined in your top-level package will typically resolve the issue [2][3].

Citations:

• 1: https://towncrier.readthedocs.io/en/24.7.0/configuration.html
• 2: https://towncrier.readthedocs.io/en/stable/tutorial.html
• 3: https://towncrier.readthedocs.io/en/24.8.0/tutorial.html
• 4: https://towncrier.readthedocs.io/en/23.11.0/configuration.html

🌐 Web query:

site:towncrier.readthedocs.io/en/stable/configuration.html "directory" "name.lower" Towncrier type

💡 Result:

In Towncrier, when configuring custom fragment types using the [[tool.towncrier.type]] array in your configuration file, the directory key specifies the subdirectory within the news fragments directory where these fragments are stored [1]. If you do not explicitly provide a value for the name key, the default value used for the fragment type name is the directory name converted to lowercase, which is expressed as name.lower [1]. For example, if you define a fragment type with directory = "Chore", the corresponding category name will default to "chore" unless otherwise specified [1].

Citations:

• 1: https://towncrier.readthedocs.io/en/stable/configuration.html

🌐 Web query:

Towncrier omitted type directory defaults to name.lower release notes

💡 Result:

In recent versions of Towncrier (specifically introduced in the 25.x release series), when defining custom fragment types within the [[tool.towncrier.type]] configuration, the directory key for a custom type now defaults to name.lower() if it is omitted [1][2][3]. This change allows users to define custom fragment types more concisely in their pyproject.toml file by omitting the directory key when they want the directory name to match the lowercase version of the fragment's name [1][4]. For example, if you define a custom type as follows: [[tool.towncrier.type]] name = "Features" Towncrier will treat the directory for these fragments as "features" by default [1][2]. This behavior differs from older versions of Towncrier, where the directory needed to be explicitly specified for custom types [5][6]. The change has been noted as a potential cause for directory location shifts in some projects upgrading to version 25, as the tool's handling of default paths and configuration options evolved [4].

Citations:

• 1: https://towncrier.readthedocs.io/en/stable/configuration.html
• 2: twisted/towncrier@21.9.0...25.8.0
• 3: twisted/towncrier@24.8.0...25.8.0rc2
• 4: Newsfragments location changed with towncrier 25 twisted/towncrier#727
• 5: https://towncrier.readthedocs.io/en/22.8.0/configuration.html
• 6: https://towncrier.readthedocs.io/en/23.11.0/configuration.html