Merge branch 'main' into fix-845-package-name-in-exception

Author: andre-motta

.github/workflows/check.yaml

@@ -11,7 +11,7 @@ jobs:
     if: ${{ !startsWith(github.ref, 'refs/tags') }}
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -32,7 +32,7 @@ jobs:
     if: ${{ !startsWith(github.ref, 'refs/tags') }}
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -53,7 +53,7 @@ jobs:
     if: ${{ !startsWith(github.ref, 'refs/tags') }}
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -74,7 +74,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ !startsWith(github.ref, 'refs/tags') }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - uses: articulate/actions-markdownlint@v1.1.0
@@ -90,7 +90,7 @@ jobs:
     if: ${{ !startsWith(github.ref, 'refs/tags') }}
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -111,11 +111,11 @@ jobs:
     if: ${{ !startsWith(github.ref, 'refs/tags') }}
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Super-Linter
-        uses: super-linter/super-linter@v8.2.1 # x-release-please-version
+        uses: super-linter/super-linter@v8.3.0 # x-release-please-version
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # To reuse the same Super-linter configuration that you use in the

.github/workflows/python-publish.yaml

@@ -19,7 +19,7 @@ jobs:
       id-token: write
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
       # with:
       #   fetch-depth: 0
     - name: Set up Python

.github/workflows/test.yaml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Get source
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
@@ -119,7 +119,7 @@ jobs:
 
     steps:
       - name: Get source
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
@@ -171,7 +171,7 @@ jobs:
       - e2e
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

AGENTS.md

@@ -76,10 +76,39 @@ for new contributors.
 
 - **No trailing whitespace**: Ensure no extra spaces at the end of lines
 - **No whitespace on blank lines**: Empty lines should contain no spaces or tabs
-- **Include a blank line as EOF**: Every file should end with a newline character
+- **End files with a single newline**: Each file should end with a single newline character (`\n`). This is a widely adopted convention recommended by PEP 8, Python's style guide. Many Unix-style text editors and tools expect files to end with a newline character and may not handle files without one properly.
 - Follow the project's existing code style and indentation patterns
 - Use consistent line endings (LF for this project)
 
+### Type Annotations
+
+- **Always add type annotations to all functions**: All functions must include type annotations for parameters and return values
+- This applies to regular functions, test functions, class methods, and async functions
+- Existing code will be updated gradually; new code must be fully typed
+- Follow the existing pattern in the codebase for consistency
+- Examples:
+
+  ```python
+  def calculate_total(items: list[int]) -> int:
+      """Calculate sum of items."""
+      return sum(items)
+
+  def test_my_feature() -> None:
+      """Test that my feature works correctly."""
+      assert my_feature() == expected_result
+  ```
+
+### Code Comments
+
+- **Avoid unnecessary comments**: Write self-documenting code with clear variable names, function names, and structure
+- **Only add comments when absolutely necessary**: Comments should be reserved for must-have cases such as:
+  - Explaining complex algorithms or non-obvious logic
+  - Documenting "why" decisions were made (not "what" the code does)
+  - Warning about edge cases or subtle bugs
+  - Explaining workarounds for external library issues
+- **Do not add comments that simply restate what the code does**: The code itself should be clear enough
+- **Prefer docstrings over comments**: Use docstrings for functions, classes, and modules to document their purpose and usage
+
 ### Testing After Code Changes
 
 After making code changes, run the following tests within a Python virtual environment to ensure code quality:

docs/concepts/dependencies.rst

@@ -0,0 +1,41 @@
+Understanding Dependency Types
+==============================
+
+Fromager tracks 5 dependency types, grouped into build-time and runtime categories.
+
+Requirement Types
+-----------------
+
+**Build-Time** (must be built before parent):
+
+- ``build-system`` — From ``pyproject.toml`` ``[build-system].requires`` with a fallback to a default provider (see PEP 517)
+- ``build-backend`` — Returned by Fromager hooks, which call PEP 517 hooks like ``get_requires_for_build_wheel`` by default
+- ``build-sdist`` — Returned by Fromager hooks, which call PEP 517 hooks by default
+
+.. note::
+
+   Both backend and sdist requirements are built before a package can be built.
+
+**Runtime** (processed after parent is built):
+
+- ``toplevel`` — Packages specified via CLI or requirements file
+- ``install`` — Runtime dependencies extracted from built wheel (``install_requires``)
+
+Key Behavior
+------------
+
+**Build dependency fails** → Parent **cannot build**
+
+**Install dependency fails** → Parent **may still build** (failure occurs at runtime)
+
+Identifying in graph.json
+-------------------------
+
+Each edge shows ``req_type``:
+
+.. code-block:: json
+
+   {"req_type": "build-system", "req": "setuptools>=45"}
+   {"req_type": "install", "req": "requests>=2.28"}
+
+Use ``fromager graph to-dot --install-only`` to filter runtime-only dependencies.

docs/concepts/index.rst

@@ -0,0 +1,8 @@
+Concepts
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   dependencies
+

docs/conf.py

@@ -15,7 +15,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Fromager"
-copyright = "2024, Fromager Authors"
+copyright = "%Y, Fromager Authors"
 author = "Fromager Authors"
 release = metadata.version("fromager")
 
@@ -30,14 +30,19 @@
     "sphinx.ext.intersphinx",
 ]
 
+# Enable MyST extensions to support reStructuredText directives in Markdown
+myst_enable_extensions = [
+    "colon_fence",
+]
+
 # Recognized suffixes
 source_suffix = {
     ".rst": "restructuredtext",
     ".md": "markdown",
 }
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "example"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 language = "English"
 
@@ -67,7 +72,7 @@
 
 
 class FromagerHookDocumenter(FunctionDocumenter):
-    """Documenter for 'autofromagehook' directive"""
+    """Documenter for 'autofromagerhook' directive"""
 
     objtype = "fromagerhook"
 
@@ -79,7 +84,7 @@ def format_name(self):
 
 
 class PyFromagerHook(PyFunction):
-    """:py:fromagehook"""
+    """:py:fromagerhook"""
 
     def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
         # hack to remove module prefix from output

docs/customization.md

@@ -154,15 +154,17 @@ bootstrap requirements, such as:
 my-package @ git+https://github.com/example/repo.git@v1.2.3
 ```
 
-For example requirements with git URLs, see:
+Example requirements file with Git URLs:
 
-.. literalinclude:: example/requirements-git-example.txt
-   :caption: requirements-git-example.txt
+```{literalinclude} example/requirements-git-example.txt
+:caption: requirements-git-example.txt
+```
 
-For a complete package configuration example, see:
+A complete package configuration example:
 
-.. literalinclude:: example/git-submodules-example.yaml
-   :caption: git-submodules-example.yaml
+```{literalinclude} example/git-submodules-example.yaml
+:caption: git-submodules-example.yaml
+```
 
 ### Build directory
 

docs/example/skip-constraints-example.md

@@ -240,6 +240,17 @@ Source hooks
 
     The return value is the ``Path`` to the newly created source distribution.
 
+Source helper functions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following helper functions are available in the ``fromager.sources`` module
+for use in custom source hooks:
+
+.. autofunction:: fromager.sources.ensure_pkg_info
+
+.. autofunction:: fromager.sources.pep517_build_sdist
+
+.. autofunction:: fromager.sources.unpack_source
 
 Wheel hooks
 -----------