User Story
As a Red Hat engineer helping productize OpenShell for internal RPM/entitlement use, and as an OpenShell contributor, I want OpenShell available as a properly reviewed Fedora package, so Fedora users and downstream consumers can install it through their normal package manager instead of install scripts or third-party COPR repos.
Problem Statement
OpenShell has no path into Fedora today. The repo carries a root-level openshell.spec intended for Fedora/EPEL, but it isn't build-ready — it consumes externally prebuilt binaries rather than compiling from source, which Koji/mock cannot support. Getting into Fedora also requires resolving vendored-dependency policy questions (~600 vendored Rust crates), a bundled library with a system equivalent (Z3), and a vendored crypto stack that bypasses system crypto policy.
Impact / Why This Matters
Several Red Hat product efforts want a supported, source-buildable path to OpenShell RPMs; Fedora-first is one of two distribution paths being evaluated internally, and landing in Fedora is more durable and community-aligned than an internal-only channel. Today the only RPM path is a hand-rolled internal COPR build — not Fedora-reviewed, not broadly redistributable.
Proposed Design
Work through the concrete engineering items below roughly in the order listed, then proceed through Fedora's package review process once the spec is review-ready.
Acceptance Criteria
Alternatives Considered
- Internal-only RPM distribution (via an internal COPR/entitlement channel) — already in progress in parallel by a separate internal team; faster to a shippable artifact but doesn't benefit the broader Fedora/community ecosystem and adds a second packaging surface to maintain long-term.
- Container-image-only distribution (status quo) — doesn't meet the needs of consumers who want a system-package-manager-installable binary.
Work Items
1. Fix %build to compile from source instead of consuming prebuilt binaries
User Story: As someone building OpenShell via rpmbuild/mock (Fedora's build path), I want %build to actually invoke cargo build, so the package can build in a network-isolated Fedora build environment.
Problem: %build only runs test -x "${OPENSHELL_PREBUILT_BINARIES_DIR}/openshell" (and equivalents for gateway/prover); %install copies binaries from that externally populated directory. No compilation happens inside the RPM build.
Impact: Disqualifying for Fedora — Koji requires building from source inside its sandboxed, network-isolated root. The current external-CI workaround has no Fedora equivalent.
Acceptance Criteria:
2. Generate Python protobuf stubs during the build
User Story: As a Fedora packager building python3-openshell, I want the protobuf stubs generated as part of the build, so the package doesn't ship stale or missing files.
Problem: python/openshell/_proto/*.py is .gitignored, produced by tasks/scripts/generate_python_proto.py. %install copies these files but nothing in %prep/%build generates them first.
Impact: Without this, the subpackage either fails to build cleanly from a clean checkout, or silently packages stale stubs from an unrelated local build — a correctness risk, not just a build failure.
Acceptance Criteria:
3. Reproducible source/vendor tarball generation script
User Story: As a packager maintaining openshell.spec across version bumps, I want a script that reproducibly regenerates Source0/Source1, so releases can be repackaged consistently and reviewed.
Problem: No such script exists upstream. An internal RHEL9 midstream spec references an equivalent make-sources.sh process, but nothing comparable is checked into this repo.
Impact: Fedora review requires packagers to explain and reproduce exactly how sources were generated — a standard reviewer question. Without a script, every version bump is ad hoc and undocumented.
Proposed Design: Single script taking a version/ref argument: archives the ref, patches the version placeholder, runs proto generation (item 2), tars the source, runs cargo vendor vendor and tars that separately. Mirrors the style/location of tasks/scripts/package-deb.sh.
Acceptance Criteria:
Alternatives Considered: Ad hoc generation at review time via generic Fedora tooling — rejected; reviewers and future packagers need something reproducible and re-runnable. Manual process each release — rejected as error-prone, especially combined with proto-stub generation.
4. Fix the version/Release scheme
User Story: As a Fedora packager, I want Version/Release to follow Fedora's guidelines, so the package can be tracked through normal Fedora update tooling.
Problem: %global openshell_version 0.0.37 is stale (current main is well past 0.0.116), and Release is a non-standard git-describe-style string.
Impact: A stale, non-standard version/release scheme blocks Fedora review outright and leaves version-bump handling undefined.
Acceptance Criteria:
5. Aggregate vendored-crate licenses into an accurate SPDX License: tag
User Story: As a packager and downstream RPM consumer, I want License: to accurately reflect every license shipped in the binary, so the package is legally accurate and passes Fedora licensing review.
Problem: openshell.spec sets License: Apache-2.0, but the binaries statically bundle ~600 vendored crates under mixed licenses (MIT, BSD variants, MPL-2.0, Unicode-3.0, ISC, etc.). %cargo_license/cargo_license_summary generate a report, but nothing reconciles it into the spec.
Impact: Fedora requires License: to be an SPDX expression covering every shipped license, not just the project's own. An inaccurate tag is a hard review blocker, and any license not on Fedora's allowed list needs a Fedora Legal conversation.
Proposed Design: Compute the aggregated SPDX expression from %cargo_license's output as part of the source-generation script (item 3), so it's derived automatically rather than hand-maintained.
Acceptance Criteria:
Alternatives Considered: One-time manual audit/hand-patch — rejected; will drift silently as dependencies change. Leave as Apache-2.0 — rejected; this is a licensing-accuracy problem independent of Fedora.
6. Resolve Z3 bundling
Already tracked separately — see #1969 ("unbundle Z3 from gateway runtime packaging"). z3-src-* is currently vendored whole for the gateway's bundled-z3 feature; Fedora already ships z3 as a system package, and the Bundled Libraries policy expects linking against it where upstream supports that. Not duplicating that issue here; resolving it is a prerequisite for this effort.
7. Document the vendored-crypto (aws-lc-rs/rustls/ring) bundling justification
User Story: As a Fedora reviewer or security-conscious consumer, I want a documented justification for why OpenShell bundles its own TLS/crypto stack instead of system OpenSSL, so the decision is auditable.
Problem: The vendor tree includes aws-lc-rs, aws-lc-sys, ring, rustls (plus tokio-rustls, quinn) — a fully vendored crypto/TLS stack that bypasses update-crypto-policies. This is a known Fedora Rust-review flashpoint and is independently flagged internally as a FIPS blocker for a separate internal RPM effort.
Impact: Without a documented justification, this will likely draw direct reviewer pushback, and it's a shared blocker with the internal RHOAI/RHAIE effort — resolving it once here benefits both.
Proposed Design: Investigate whether an OpenSSL-backed feature flag is feasible without a large refactor; if not, write the formal bundling-exception rationale for Fedora review.
Acceptance Criteria:
Alternatives Considered: Switch to OpenSSL-backed TLS now — likely correct long-term but too large for this push; tracked as a documented gap instead. Say nothing, let a reviewer raise it — rejected; better to get ahead of a known blocker.
8. Add CI job to build/validate openshell.spec
User Story: As a maintainer of openshell.spec, I want CI to actually build the package, so future changes don't silently break Fedora buildability again.
Problem: tasks/scripts/test-packaging-assets.sh only does string-content assertions against the spec — it never invokes rpmbuild/mock. No workflow builds the RPM from source.
Impact: Once the above fixes land, nothing stops a future change from silently re-breaking the Fedora build, since nothing exercises it. Overlaps with already-open #3454.
Proposed Design: Add a packaging CI job using mock in a container, following the existing license-headers-style job structure in .github/workflows/branch-checks.yml.
Acceptance Criteria:
Alternatives Considered: Periodic manual builds — rejected; exactly the kind of check that rots without automation. Only catch breaks via Rawhide/COPR post-merge — rejected as too late.
Related: #1969, #2204, #3454
Checklist
User Story
As a Red Hat engineer helping productize OpenShell for internal RPM/entitlement use, and as an OpenShell contributor, I want OpenShell available as a properly reviewed Fedora package, so Fedora users and downstream consumers can install it through their normal package manager instead of install scripts or third-party COPR repos.
Problem Statement
OpenShell has no path into Fedora today. The repo carries a root-level
openshell.specintended for Fedora/EPEL, but it isn't build-ready — it consumes externally prebuilt binaries rather than compiling from source, which Koji/mock cannot support. Getting into Fedora also requires resolving vendored-dependency policy questions (~600 vendored Rust crates), a bundled library with a system equivalent (Z3), and a vendored crypto stack that bypasses system crypto policy.Impact / Why This Matters
Several Red Hat product efforts want a supported, source-buildable path to OpenShell RPMs; Fedora-first is one of two distribution paths being evaluated internally, and landing in Fedora is more durable and community-aligned than an internal-only channel. Today the only RPM path is a hand-rolled internal COPR build — not Fedora-reviewed, not broadly redistributable.
Proposed Design
Work through the concrete engineering items below roughly in the order listed, then proceed through Fedora's package review process once the spec is review-ready.
Acceptance Criteria
openshell.specbuilds viarpmbuild/mockfrom source with no network access after%prepLicense:Alternatives Considered
Work Items
1. Fix
%buildto compile from source instead of consuming prebuilt binariesUser Story: As someone building OpenShell via
rpmbuild/mock(Fedora's build path), I want%buildto actually invokecargo build, so the package can build in a network-isolated Fedora build environment.Problem:
%buildonly runstest -x "${OPENSHELL_PREBUILT_BINARIES_DIR}/openshell"(and equivalents for gateway/prover);%installcopies binaries from that externally populated directory. No compilation happens inside the RPM build.Impact: Disqualifying for Fedora — Koji requires building from source inside its sandboxed, network-isolated root. The current external-CI workaround has no Fedora equivalent.
Acceptance Criteria:
%buildrunscargo build --release --offline --lockedforopenshell,openshell-gateway,openshell-proveragainst the%cargo_prep-vendored sourcesmockchroot with networking disabledOPENSHELL_PREBUILT_BINARIES_DIRor similar2. Generate Python protobuf stubs during the build
User Story: As a Fedora packager building
python3-openshell, I want the protobuf stubs generated as part of the build, so the package doesn't ship stale or missing files.Problem:
python/openshell/_proto/*.pyis.gitignored, produced bytasks/scripts/generate_python_proto.py.%installcopies these files but nothing in%prep/%buildgenerates them first.Impact: Without this, the subpackage either fails to build cleanly from a clean checkout, or silently packages stale stubs from an unrelated local build — a correctness risk, not just a build failure.
Acceptance Criteria:
%prep/%buildruns proto generation offline against vendoredproto/*.protoBuildRequiresthis needs (e.g.python3-grpcio-tools)%checkverifies stub files exist and import correctly3. Reproducible source/vendor tarball generation script
User Story: As a packager maintaining
openshell.specacross version bumps, I want a script that reproducibly regeneratesSource0/Source1, so releases can be repackaged consistently and reviewed.Problem: No such script exists upstream. An internal RHEL9 midstream spec references an equivalent
make-sources.shprocess, but nothing comparable is checked into this repo.Impact: Fedora review requires packagers to explain and reproduce exactly how sources were generated — a standard reviewer question. Without a script, every version bump is ad hoc and undocumented.
Proposed Design: Single script taking a version/ref argument: archives the ref, patches the version placeholder, runs proto generation (item 2), tars the source, runs
cargo vendor vendorand tars that separately. Mirrors the style/location oftasks/scripts/package-deb.sh.Acceptance Criteria:
openshell-<version>.tar.gzandopenshell-<version>-vendor.tar.xzfrom a given git refcargo vendoragainst the workspaceCargo.lockopenshell.spec's header commentAlternatives Considered: Ad hoc generation at review time via generic Fedora tooling — rejected; reviewers and future packagers need something reproducible and re-runnable. Manual process each release — rejected as error-prone, especially combined with proto-stub generation.
4. Fix the version/Release scheme
User Story: As a Fedora packager, I want
Version/Releaseto follow Fedora's guidelines, so the package can be tracked through normal Fedora update tooling.Problem:
%global openshell_version 0.0.37is stale (currentmainis well past0.0.116), andReleaseis a non-standard git-describe-style string.Impact: A stale, non-standard version/release scheme blocks Fedora review outright and leaves version-bump handling undefined.
Acceptance Criteria:
Versiontracks the actual current releaseReleasefollows a Fedora-conformant scheme (e.g.%autorelease/%autochangelog)5. Aggregate vendored-crate licenses into an accurate SPDX
License:tagUser Story: As a packager and downstream RPM consumer, I want
License:to accurately reflect every license shipped in the binary, so the package is legally accurate and passes Fedora licensing review.Problem:
openshell.specsetsLicense: Apache-2.0, but the binaries statically bundle ~600 vendored crates under mixed licenses (MIT, BSD variants, MPL-2.0, Unicode-3.0, ISC, etc.).%cargo_license/cargo_license_summarygenerate a report, but nothing reconciles it into the spec.Impact: Fedora requires
License:to be an SPDX expression covering every shipped license, not just the project's own. An inaccurate tag is a hard review blocker, and any license not on Fedora's allowed list needs a Fedora Legal conversation.Proposed Design: Compute the aggregated SPDX expression from
%cargo_license's output as part of the source-generation script (item 3), so it's derived automatically rather than hand-maintained.Acceptance Criteria:
License:(per subpackage as needed) is a correct SPDX union of all shipped licensesCargo.lockchangesAlternatives Considered: One-time manual audit/hand-patch — rejected; will drift silently as dependencies change. Leave as
Apache-2.0— rejected; this is a licensing-accuracy problem independent of Fedora.6. Resolve Z3 bundling
Already tracked separately — see #1969 ("unbundle Z3 from gateway runtime packaging").
z3-src-*is currently vendored whole for the gateway'sbundled-z3feature; Fedora already shipsz3as a system package, and the Bundled Libraries policy expects linking against it where upstream supports that. Not duplicating that issue here; resolving it is a prerequisite for this effort.7. Document the vendored-crypto (aws-lc-rs/rustls/ring) bundling justification
User Story: As a Fedora reviewer or security-conscious consumer, I want a documented justification for why OpenShell bundles its own TLS/crypto stack instead of system OpenSSL, so the decision is auditable.
Problem: The vendor tree includes
aws-lc-rs,aws-lc-sys,ring,rustls(plustokio-rustls,quinn) — a fully vendored crypto/TLS stack that bypassesupdate-crypto-policies. This is a known Fedora Rust-review flashpoint and is independently flagged internally as a FIPS blocker for a separate internal RPM effort.Impact: Without a documented justification, this will likely draw direct reviewer pushback, and it's a shared blocker with the internal RHOAI/RHAIE effort — resolving it once here benefits both.
Proposed Design: Investigate whether an OpenSSL-backed feature flag is feasible without a large refactor; if not, write the formal bundling-exception rationale for Fedora review.
Acceptance Criteria:
Alternatives Considered: Switch to OpenSSL-backed TLS now — likely correct long-term but too large for this push; tracked as a documented gap instead. Say nothing, let a reviewer raise it — rejected; better to get ahead of a known blocker.
8. Add CI job to build/validate
openshell.specUser Story: As a maintainer of
openshell.spec, I want CI to actually build the package, so future changes don't silently break Fedora buildability again.Problem:
tasks/scripts/test-packaging-assets.shonly does string-content assertions against the spec — it never invokesrpmbuild/mock. No workflow builds the RPM from source.Impact: Once the above fixes land, nothing stops a future change from silently re-breaking the Fedora build, since nothing exercises it. Overlaps with already-open #3454.
Proposed Design: Add a
packagingCI job usingmockin a container, following the existinglicense-headers-style job structure in.github/workflows/branch-checks.yml.Acceptance Criteria:
openshell.specinmock(or equivalent) with networking disabled after%prepopenshell.spec,Cargo.toml/Cargo.lock,deploy/rpm/, relevantpython/openshell/sourcesAlternatives Considered: Periodic manual builds — rejected; exactly the kind of check that rots without automation. Only catch breaks via Rawhide/COPR post-merge — rejected as too late.
Related: #1969, #2204, #3454
Checklist