From 580fd172ba5aef43c558976c569a171c93f46978 Mon Sep 17 00:00:00 2001 From: Vinit Vishwakarma Date: Thu, 1 Jan 2026 15:10:36 +0530 Subject: [PATCH 1/2] Fix broken AboutCode logo link in GSoC 2017 page --- docs/source/archive/gsoc/org_pages/gsoc_2017.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/archive/gsoc/org_pages/gsoc_2017.rst b/docs/source/archive/gsoc/org_pages/gsoc_2017.rst index d6f595a..400120b 100644 --- a/docs/source/archive/gsoc/org_pages/gsoc_2017.rst +++ b/docs/source/archive/gsoc/org_pages/gsoc_2017.rst @@ -2,7 +2,7 @@ Google Summer of Code 2017 ========================== -.. image:: https://cdn.rawgit.com/wiki/nexB/aboutcode/aboutcode_logo.svg +.. image:: https://raw.githubusercontent.com/wiki/aboutcode-org/aboutcode/aboutcode_logo.svg :target: http://www.aboutcode.org/ :alt: AboutCode Logo From 32b1b24ebb9bb25a25bf135d7dc41c23c78b326d Mon Sep 17 00:00:00 2001 From: Vinit Vishwakarma Date: Sun, 18 Jan 2026 20:03:04 +0530 Subject: [PATCH 2/2] Fixed 4 Issues --- docs/source/contributing.rst | 1 + docs/source/contributing/contrib_doc.rst | 4 +- docs/source/contributing/release_news.rst | 85 +++++++++++++++++++ .../writing_good_commit_messages.rst | 10 ++- docs/source/index.rst | 19 +++++ docs/source/news/index.rst | 18 ++++ docs/source/news/overview.rst | 18 ++++ .../news/posts/2021-12-17-scancode-io.rst | 17 ++++ docs/source/privacy-policy.rst | 81 ++++++++++++++++++ docs/source/standards/ABC-0000-template.rst | 42 +++++++++ docs/source/standards/index.rst | 42 +++++++++ tools/generate_release_post.py | 85 +++++++++++++++++++ 12 files changed, 417 insertions(+), 5 deletions(-) create mode 100644 docs/source/contributing/release_news.rst create mode 100644 docs/source/news/index.rst create mode 100644 docs/source/news/overview.rst create mode 100644 docs/source/news/posts/2021-12-17-scancode-io.rst create mode 100644 docs/source/privacy-policy.rst create mode 100644 docs/source/standards/ABC-0000-template.rst create mode 100644 docs/source/standards/index.rst create mode 100644 tools/generate_release_post.py diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 7c039b8..b98e39f 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -34,3 +34,4 @@ Contribution Guidelines: contributing/writing_good_commit_messages contributing/testing contributing/contrib_doc + contributing/release_news diff --git a/docs/source/contributing/contrib_doc.rst b/docs/source/contributing/contrib_doc.rst index b1758be..e71be79 100644 --- a/docs/source/contributing/contrib_doc.rst +++ b/docs/source/contributing/contrib_doc.rst @@ -97,7 +97,9 @@ following commands are examples:: git add source/index.rst git add source/how-to-scan.rst git status - git commit -m "New how-to document that explains how to scan" + # Prefer full issue URLs for cross-repo clarity. Use shorthand #123 only + # if the change will stay in the same repository. + git commit -m "New how-to document that explains how to scan https://github.com/aboutcode-org/aboutcode/issues/106" git status git push git status diff --git a/docs/source/contributing/release_news.rst b/docs/source/contributing/release_news.rst new file mode 100644 index 0000000..aa3321d --- /dev/null +++ b/docs/source/contributing/release_news.rst @@ -0,0 +1,85 @@ +######################################## +Publishing release news to aboutcode.org +######################################## + +Goal +==== +Provide a repeatable way for any AboutCode project to publish a release +announcement to the AboutCode news feed with minimal manual steps. + +Generate a post locally +======================= + +Use the helper script in this repo to create a news file in +``docs/source/news/posts``: + +.. code-block:: bash + + python tools/generate_release_post.py \ + --project "ScanCode Toolkit" \ + --version "32.0.0" \ + --release-url "https://github.com/aboutcode-org/scancode-toolkit/releases/tag/v32.0.0" + +This writes a dated file (for example, +``docs/source/news/posts/2026-01-18-scancode-toolkit.rst``). Stage, commit, and +open a PR to `aboutcode-org/aboutcode`. + +Automate with GitHub Actions (template) +======================================= + +Add a workflow in the releasing project that runs on ``release`` events and +opens a PR to the aboutcode site. This template assumes you store a token with +push rights to your fork of ``aboutcode-org/aboutcode`` as +``ABOUTCODE_DOCS_PAT``. + +.. code-block:: yaml + + name: Publish release news + on: + release: + types: [published] + + jobs: + announce: + runs-on: ubuntu-latest + steps: + - name: Check out aboutcode site + uses: actions/checkout@v4 + with: + repository: ${{ github.repository_owner }}/aboutcode + token: ${{ secrets.ABOUTCODE_DOCS_PAT }} + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install deps (docs extra) + run: | + python -m pip install --upgrade pip + pip install -e .[docs] + + - name: Generate news post + run: | + python tools/generate_release_post.py \ + --project "${{ github.event.repository.name }}" \ + --version "${{ github.event.release.tag_name }}" \ + --release-url "${{ github.event.release.html_url }}" + + - name: Create pull request + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.ABOUTCODE_DOCS_PAT }} + branch: release-news/${{ github.event.repository.name }}-${{ github.event.release.tag_name }} + commit-message: "Add news post for ${{ github.event.repository.name }} ${{ github.event.release.tag_name }}" + title: "Add news post for ${{ github.event.repository.name }} ${{ github.event.release.tag_name }}" + body: "Automated release news post for ${{ github.event.release.html_url }}" + +Notes and expectations +====================== +- Keep posts concise: title, short summary, highlight bullets, and links. +- The script is idempotent per date + project; reruns on the same day overwrite + the file unless a new version is provided. +- Review the generated post before merging; adjust highlights as needed. +- If you cannot grant a token to push directly, run the workflow in a fork and + open a PR manually. diff --git a/docs/source/contributing/writing_good_commit_messages.rst b/docs/source/contributing/writing_good_commit_messages.rst index d604d41..621f517 100644 --- a/docs/source/contributing/writing_good_commit_messages.rst +++ b/docs/source/contributing/writing_good_commit_messages.rst @@ -19,7 +19,10 @@ The main style points are these: Subject: -- Add a issue number at the end of the line when available as in "#234" +- Prefer full issue URLs (e.g. ``https://github.com/aboutcode-org/aboutcode/issues/234``) + to keep references valid if code moves to another repo. +- Shorthand ``#234`` is acceptable only when the work is guaranteed to remain in + the same repository. - Limit the subject line to 50 characters - Capitalize the subject line - Do not end the subject line with a period @@ -38,9 +41,8 @@ Body: Other comments: -We like to suffix the subject line with an issue number. If this was a -trivial change it may not have one though. If it had one a you would use -``#156`` as a suffix to the first line. +We like to suffix the subject line with an issue reference. Use the full URL by +default; shorthand ``#156`` only if the commit will stay in the same repository. We like to tell why the commit is there and use an imperative style, like if you were giving an order to the codebase with your commit: diff --git a/docs/source/index.rst b/docs/source/index.rst index e13bf63..88bffb2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -27,6 +27,15 @@ Overview aboutcode-project-overview +******** +Standards +******** + +.. toctree:: + :maxdepth: 2 + + standards/index + ************ Contributing ************ @@ -36,6 +45,15 @@ Contributing contributing +**** +News +**** + +.. toctree:: + :maxdepth: 1 + + news/index + ****** Others ****** @@ -45,4 +63,5 @@ Others aboutcode-data/abcd archive + privacy-policy license diff --git a/docs/source/news/index.rst b/docs/source/news/index.rst new file mode 100644 index 0000000..5a0a3e4 --- /dev/null +++ b/docs/source/news/index.rst @@ -0,0 +1,18 @@ +############################ +News and release updates +############################ + +AboutCode projects can publish release announcements here so readers see updates +in one place. + +- For instructions on generating a post automatically, see + :doc:`../contributing/release_news`. +- Posts live under the ``news/posts`` directory and are typically created by the + automation script in ``tools/generate_release_post.py``. + +.. toctree:: + :maxdepth: 1 + :glob: + + overview + posts/* diff --git a/docs/source/news/overview.rst b/docs/source/news/overview.rst new file mode 100644 index 0000000..666e2a0 --- /dev/null +++ b/docs/source/news/overview.rst @@ -0,0 +1,18 @@ +############################# +How release posts are structured +############################# + +Release posts are short and consistent so they can be generated automatically. +Each post includes: + +- A title in the form `` released``. +- A one-paragraph summary and bullet points for highlights. +- A link to the project release page. +- Optional links to changelogs, installation notes, or SBOMs if available. + +Posts are stored in ``docs/source/news/posts`` and named with the date prefix, +for example: ``2026-01-18-scancode-toolkit.rst``. + +To add a post, run the helper script (documented in +:doc:`../contributing/release_news`) or author a file manually following the +same structure. diff --git a/docs/source/news/posts/2021-12-17-scancode-io.rst b/docs/source/news/posts/2021-12-17-scancode-io.rst new file mode 100644 index 0000000..47f5187 --- /dev/null +++ b/docs/source/news/posts/2021-12-17-scancode-io.rst @@ -0,0 +1,17 @@ +################################ +ScanCode.io 21.12.17 released +################################ + +ScanCode.io 21.12.17 is available. This release delivers pipeline and UI +improvements for scanning and reviewing SBOM data produced by ScanCode Toolkit. + +Highlights +========== +- Streamlined pipeline steps for common container and archive workflows. +- Improved result review experience in the web UI. +- Updated dependencies and security fixes. + +Links +===== +- Release notes: https://github.com/aboutcode-org/scancode.io/releases +- Project page: https://scancode.io diff --git a/docs/source/privacy-policy.rst b/docs/source/privacy-policy.rst new file mode 100644 index 0000000..6fc8d12 --- /dev/null +++ b/docs/source/privacy-policy.rst @@ -0,0 +1,81 @@ +################ +Privacy Policy +################ + +This page describes how the AboutCode community websites and documentation +handle personal data. It is intentionally simple and covers only what we +currently do. We will update it when practices change. + +Scope +===== + +- This policy applies to AboutCode-operated sites and documentation, including + the content served from this repository and its published builds + (for example, on Read the Docs). +- Individual AboutCode projects may run their own services (for example, + demo deployments or APIs). Those services may have additional terms; check + their documentation or service pages. + +What we collect +=============== + +- Web server logs created by our hosting providers (for example, the IP + address, requested URL, timestamp, user agent). These are used for routine + operations, troubleshooting, and abuse prevention. +- Information you choose to share when you participate in our communities + (for example, names and emails in commits, issues, or mailing lists, or + profile information in chats). This data is public because you chose to + publish it. +- Optional metrics collected by the platforms we use (for example, GitHub or + Read the Docs may record usage for security and performance). That data is + governed by the platform's own privacy terms. + +What we do not do +================= + +- We do not sell personal data. +- We do not run advertising or behavioral tracking on the documentation site. +- We do not use third-party analytics or cookies on the documentation site + beyond what the hosting platforms require to operate. + +How we use the data we have +=========================== + +- Operate and secure the sites and community services. +- Detect and mitigate abuse (for example, denial of service or spam). +- Improve documentation quality based on aggregated, non-identifying usage + trends made available by the hosting platforms. + +Retention +========= + +- Hosting platforms control retention of their operational logs; these are + typically short-lived and used for security and performance. +- Public contribution data (for example, issues, commits, and mailing list + archives) remains publicly visible as part of the project history unless + removed for legal or safety reasons. + +Sharing +======= + +- Hosting providers such as GitHub and Read the Docs process and may share data + under their own terms and applicable law. +- We may disclose data if required to comply with legal obligations or to + protect the security of the project and its community. + +Your choices and requests +========================= + +- You can avoid publishing personal data by limiting what you include in public + contributions (for example, use a non-identifying email for commits). +- You can request removal of personal data that appears in our documentation or + project materials when feasible and legally permissible. +- For analytics or cookies controlled by the hosting platforms, refer to their + privacy settings and policies. + +Contact +======= + +Questions or requests about this policy can be sent to **info@aboutcode.org**. + +Last updated: 2026-01-18 diff --git a/docs/source/standards/ABC-0000-template.rst b/docs/source/standards/ABC-0000-template.rst new file mode 100644 index 0000000..2ba48b0 --- /dev/null +++ b/docs/source/standards/ABC-0000-template.rst @@ -0,0 +1,42 @@ +########################## +ABC-0000: Title goes here +########################## + +:Status: Draft +:Created: 2026-01-18 +:Authors: Your Name +:Related: (issue/PR links) + +Summary +======= +A short, reader-friendly summary (3–5 sentences) of the proposal. + +Motivation +========== +- What problem are we solving? +- Why now? Who benefits? + +Proposal +======== +- The concrete change being proposed (policies, standards, processes). +- Scope: which AboutCode projects are affected? +- Defaults and configuration (if applicable). + +Impact +====== +- Benefits and trade-offs. +- Migration/rollout steps (if any). +- Compatibility considerations for downstream projects. + +Alternatives considered +======================= +- Briefly list rejected or non-chosen options and why. + +Adoption and follow-up +====================== +- How this will be enforced (lint, CI, docs, checklists, etc.). +- Owners for ongoing maintenance, if needed. + +Changelog for this ABC +====================== +- 2026-01-18: Initial draft diff --git a/docs/source/standards/index.rst b/docs/source/standards/index.rst new file mode 100644 index 0000000..a605724 --- /dev/null +++ b/docs/source/standards/index.rst @@ -0,0 +1,42 @@ +############################### +AboutCode proposals (ABC series) +############################### + +Org-wide standards and policies are captured as AboutCode proposals, numbered +``ABC-XXXX``. Each proposal lives in this repository, is reviewed in a Pull +Request, and—once accepted—serves as the canonical reference for the topic +(coding standards, security practices, governance, etc.). + +Process (lightweight) +===================== +- Copy the template at :doc:`ABC-0000-template` to a new file named + ``ABC--.rst``. +- Open a PR in this repo adding the new proposal under ``docs/source/standards``. +- Reviewers discuss in the PR; when accepted, the status becomes **Accepted**. +- If a proposal is replaced or declined, set status to **Superseded** or + **Rejected** but keep the document for history. + +Numbering +========= +- Use four digits: ``ABC-0001``, ``ABC-0002``, … +- Start at 0001 for new proposals (coordinated by the PR author/reviewer to + avoid collisions). + +Statuses +======== +- **Draft**: proposed, under discussion +- **Accepted**: approved and in effect +- **Superseded**: replaced by a newer ABC +- **Rejected/Withdrawn**: will not proceed + +Where these are published +========================= +- Source lives in this repo under ``docs/source/standards``. +- Built docs (e.g., Read the Docs) will include them so all projects can link to + the canonical copy. + +.. toctree:: + :maxdepth: 1 + + ABC-0000-template + diff --git a/tools/generate_release_post.py b/tools/generate_release_post.py new file mode 100644 index 0000000..797a4f2 --- /dev/null +++ b/tools/generate_release_post.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +""" +Generate a news post for an AboutCode project release. + +This writes a reStructuredText file into docs/source/news/posts with a +consistent title and link block. It is intended to be run from CI on release +publishes or locally before opening a PR. +""" +from __future__ import annotations + +import argparse +from datetime import date +from pathlib import Path +import re +import sys +from textwrap import dedent + + +def slugify(text: str) -> str: + text = text.strip().lower() + text = re.sub(r"[^a-z0-9]+", "-", text) + text = text.strip("-") + return text or "release" + + +def build_content(project: str, version: str, release_url: str, summary: str) -> str: + title = f"{project} {version} released" + underline = "#" * len(title) + summary = summary or f"{project} {version} is now available." + body = f""" + {title} + {underline} + + {summary} + + Highlights + ========== + - Release link: {release_url} + + Links + ===== + - Release page: {release_url} + """ + return dedent(body).lstrip("\n") + + +def write_post(posts_dir: Path, filename: str, content: str, force: bool) -> Path: + posts_dir.mkdir(parents=True, exist_ok=True) + path = posts_dir / filename + if path.exists() and not force: + raise FileExistsError(f"Post already exists: {path}") + path.write_text(content, encoding="utf-8") + return path + + +def parse_args(argv: list[str]) -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Generate a release news post") + parser.add_argument("--project", required=True, help="Project name") + parser.add_argument("--version", required=True, help="Release version tag") + parser.add_argument("--release-url", required=True, help="Release page URL") + parser.add_argument("--date", default=date.today().isoformat(), help="ISO date for the post filename (default: today)") + parser.add_argument("--posts-dir", default="docs/source/news/posts", help="Directory for news posts") + parser.add_argument("--summary", default="", help="One-line summary for the post body") + parser.add_argument("--force", action="store_true", help="Overwrite an existing post if present") + return parser.parse_args(argv) + + +def main(argv: list[str]) -> int: + args = parse_args(argv) + slug = slugify(args.project) + filename = f"{args.date}-{slug}.rst" + content = build_content(args.project, args.version, args.release_url, args.summary) + + try: + path = write_post(Path(args.posts_dir), filename, content, args.force) + except FileExistsError as e: + sys.stderr.write(f"{e}\n") + return 1 + + sys.stdout.write(f"Created news post: {path}\n") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:]))