diff --git a/README.rst b/README.rst index 6fc9233..c31f8cf 100644 --- a/README.rst +++ b/README.rst @@ -39,7 +39,7 @@ Work together - `Skills repository`_ * - Public CI - Document testing needs and discuss support for additional hardware. - - `CI requirements`_ + - `CI setup guide `_ and `CI requirements`_ * - Security practices - Review project security improvements and shared processes. - `Security work`_ @@ -64,6 +64,10 @@ topics through the mailing list or the ``wg-open-source`` channel on `UXL Slack` Bring a contribution -------------------- +Pending discussion: `oneMath domain-split decision brief +`_. The twelve implementation tasks remain +open pending a new Working Group decision. + * **A shared task or question:** check `Open issues`_ and discuss scope with the relevant maintainers before starting. * **A significant cross-project proposal:** follow the `RFC process`_. diff --git a/meetings/topics/math-domain-split.md b/meetings/topics/math-domain-split.md new file mode 100644 index 0000000..00bca8e --- /dev/null +++ b/meetings/topics/math-domain-split.md @@ -0,0 +1,47 @@ +# oneMath domain split: WG decision brief + +**Status: needs a new Working Group decision.** This brief prepares the discussion; +it does not approve, cancel or supersede the original direction. + +## Why revisit it + +The [June 25, 2024 minutes](../notes/2024-06-25.rst) record consensus to proceed +with splitting the former oneMKL interfaces project by domain, with implementation +details still to resolve. Twelve implementation tasks remain open. + +The current [oneMath source tree](https://github.com/uxlfoundation/oneMath/tree/develop/src) +contains BLAS, DFT, LAPACK, RNG and sparse BLAS together. That layout and the +oneMath rename do not establish that the split was cancelled or completed. +During the September 10, 2026 maintenance review, WG co-chair John Melonakos +confirmed that a new WG decision is needed. + +## Decision to record + +Discuss whether to continue the separate-repository plan, revise its scope, or +retain the domains together. For the selected direction, record the rationale, +affected projects, compatibility implications and links to the decision minutes. + +Consider shared types and exceptions, dependencies between domains, release and +version coordination, CI cost, contributor navigation and migration effort. +Refer to the [dynamic oneAPI specification](https://uxlfoundation.org/specifications/oneapi/technical-overview/) +and current project documentation for interfaces; this brief does not change them. + +## Tasks affected + +| Work | Existing tasks | +| --- | --- | +| Shared repository and common header | [#126](https://github.com/uxlfoundation/open-source-working-group/issues/126), [#127](https://github.com/uxlfoundation/open-source-working-group/issues/127) | +| BLAS repository and code | [#128](https://github.com/uxlfoundation/open-source-working-group/issues/128), [#133](https://github.com/uxlfoundation/open-source-working-group/issues/133) | +| DFT repository and code | [#129](https://github.com/uxlfoundation/open-source-working-group/issues/129), [#134](https://github.com/uxlfoundation/open-source-working-group/issues/134) | +| LAPACK repository and code | [#130](https://github.com/uxlfoundation/open-source-working-group/issues/130), [#135](https://github.com/uxlfoundation/open-source-working-group/issues/135) | +| RNG repository and code | [#131](https://github.com/uxlfoundation/open-source-working-group/issues/131), [#136](https://github.com/uxlfoundation/open-source-working-group/issues/136) | +| Sparse BLAS repository and code | [#132](https://github.com/uxlfoundation/open-source-working-group/issues/132), [#137](https://github.com/uxlfoundation/open-source-working-group/issues/137) | + +## Follow-through + +Keep the tasks open pending the decision. Afterwards, update their scope and +completion criteria, record agreed owners for continuing work, and close only +tasks explicitly superseded or supported by completion evidence. Link each update +to the decision so the historical agreement remains understandable. + +[Meeting archive](../notes/README.rst) · [Working Group home](../../README.rst) diff --git a/project-infrastructure/project-ci-documentation.md b/project-infrastructure/project-ci-documentation.md index 1bf426b..64572ef 100644 --- a/project-infrastructure/project-ci-documentation.md +++ b/project-infrastructure/project-ci-documentation.md @@ -1,5 +1,9 @@ # Project Infrastructure for CI and CD +For setup and deployment recommendations, start with the +[public CI guide](public-ci-guide.md). This inventory tracks project-specific +requirements and evidence. + Documentation maintenance review: 2026-09-09. This date does not certify runner availability. Project representatives should add a last-verified date and public workflow/log links when updating their section. Entries marked unverified need diff --git a/project-infrastructure/public-ci-guide.md b/project-infrastructure/public-ci-guide.md new file mode 100644 index 0000000..d005279 --- /dev/null +++ b/project-infrastructure/public-ci-guide.md @@ -0,0 +1,104 @@ +# Configuring and deploying public project CI + +Use this guide to establish reproducible public build and test workflows. It +provides recommendations for project maintainers, not a new foundation policy +or a promise of shared hardware. The [CI inventory](project-ci-documentation.md) +records requirements and dated execution evidence. + +## 1. Define what the workflow must prove + +Choose one initial build/test target and record its operating system, processor, +compiler, dependencies and test command. Distinguish compiling the library, +running functional tests, measuring performance and publishing a release. +Documentation builds and static analysis do not establish functional coverage. + +Put reproducible setup, build and test commands in the project repository so +contributors can run them locally. Record dependency versions and the source +revision. For hardware-specific tests, identify the actual device and driver; +a runner label or emulated target alone is not proof of physical device coverage. + +## 2. Choose the execution environment + +Prefer GitHub-hosted runners when they meet the target's needs. For specialized +hardware, first establish an owner, permitted repositories, access route, +isolation model and update process. Do not reuse an old capacity catalogue as +evidence that a machine is available. + +GitHub recommends avoiding self-hosted runners for public repositories because +pull requests can execute untrusted code. Review its +[runner access guidance](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/manage-access) +before choosing that design. If specialized hardware requires self-hosting, +document how untrusted changes are isolated from credentials, other jobs and +internal networks. A container or manual approval alone does not establish that +isolation. + +For autoscaling, use clean, single-job environments and retain runner diagnostics +outside the disposable machine. Plan how the machine is reset or replaced after +each job; deregistration alone does not wipe it. See GitHub's +[ephemeral runner guidance](https://docs.github.com/en/actions/reference/runners/self-hosted-runners). + +## 3. Configure a small, reviewable workflow + +Start with one target before expanding the matrix. Use a pull-request trigger +for contributor validation and an appropriate main-branch or scheduled trigger +for integration checks. Keep publishing credentials out of contributor testing. + +Set explicit minimum token permissions, pin third-party actions to verified +full commit hashes, and avoid placing untrusted PR titles or other event text +directly into shell commands. Do not combine privileged `pull_request_target` +execution with checkout and execution of untrusted contributor code. Review +[GitHub's secure-use guidance](https://docs.github.com/en/actions/reference/security/secure-use) +when configuring these boundaries. + +Use stable job names, bounded timeouts and cancellation of obsolete runs where +appropriate. Make build or test failures fail the check. Document intentional +path/domain filters so a skipped job cannot be mistaken for tested coverage. + +## 4. Validate before relying on the check + +Run a known-good revision and inspect individual build/test steps. Then use a +temporary test change that should fail and verify that the check reports failure. +Exercise the contributor/fork path using harmless test changes in the intended +isolated environment. Confirm that logs identify the tested revision and target. + +Check cancellation, unavailable-runner behavior and any conditional skips. If a +check will become required, first confirm its name and triggering behavior match +the intended contribution paths; an absent check can leave a PR waiting forever. + +For examples of real execution, use the +[verified workflow evidence](project-ci-documentation.md#public-workflow-evidence). +Those examples are evidence for their stated targets, not templates guaranteeing +the same coverage in another project. + +## 5. Publish the result and hand it over + +Add the workflow and local reproduction instructions through the project's normal +review process. Record the following in its CI documentation and update the shared +inventory with a verification date and evidence link: + +| Record | What to include | +| --- | --- | +| Coverage | Build/test targets, hardware, software versions and known gaps | +| Entry points | Workflow, triggers, required-check names and local commands | +| Evidence | Successful run and deliberate-failure validation on the tested revision | +| Operations | Agreed primary/backup contact, access route and update responsibility | +| Resources | Shared or dedicated capacity, limits and unavailable-runner behavior | +| Recovery | How to stop dispatch, replace an unhealthy runner and restore service | + +Report private operational details through the project's restricted channels. +Public documentation should still explain how contributors obtain help and +interpret failures. + +## 6. Keep the setup useful + +Review failures and queue delays, update images and dependencies, and revalidate +after changes to drivers, compilers or hardware. Give infrastructure outages a +clear explanation so contributors can distinguish them from code regressions. +If a runner is retired, update its workflow and inventory entry together. + +If publishing artifacts is added later, document it as a separate process with +its own permissions and verification. Public test infrastructure does not by +itself establish release provenance or release readiness. + +[CI inventory](project-ci-documentation.md) · [Security guide](../security/README.md) +· [Working Group home](../README.rst)