Skip to content

Restructure Require-Bundle chapter into split packages, re-export and trade-offs - #76

Open
laeubi wants to merge 1 commit into
osgi:mainfrom
laeubi:recommended_spec_update
Open

laeubi wants to merge 1 commit into
osgi:mainfrom
laeubi:recommended_spec_update

Conversation

@laeubi

@laeubi laeubi commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Rationale

"Split Package Compatibility" and "Issues With Requiring Bundles" mixed three topics: split packages, re-export and Require-Bundle itself.
The title suggested backward compatibility, "subset" was undefined, and the split-package drawbacks were hard to connect to Require-Bundle.

Changes

  • Split Packages: definition, sources, meaning of "compatible" with an example, legitimate uses, recommendation, drawbacks
  • Re-exporting Required Bundles: compatibility bridge for refactorings
  • Require-Bundle versus Import-Package: historic practice, valid use cases, drawbacks, recommendation
  • Each section acknowledges legacy use cases and ends with a "Recommended:" note, so readers are guided without being blamed

Not changed

Existing drawback items (Completeness, Ordering, Performance, Confusing) and the example in Require-Bundle are kept as they were.

Please review

  • Is the definition of "compatible" (source subset) accurate with respect to the resolver behaviour?
  • Is the tone of the "Recommended:" notes appropriate for a spec?

I tried to generate a diff spec PDF here: changes-highlighted.pdf

… trade-offs

The former "Split Package Compatibility" and "Issues With Requiring
Bundles" sections mixed three separate topics. The "compatibility"
title suggested backward compatibility, "subset" was undefined, and
the split package drawbacks hid behind a generic "issues" heading,
so readers not using split packages saw no reason to avoid
Require-Bundle.

Split the text into three sections:

- Split Packages: definition, sources, what "compatible" means with
  an example, legitimate reasons for split packages, a
  recommendation and the drawbacks.
- Re-exporting Required Bundles: presented as a compatibility bridge
  for refactorings (moving a package to a new bundle without breaking
  existing Require-Bundle clients), with its own drawbacks.
- Require-Bundle versus Import-Package: acknowledges the historic
  practice and valid use cases, lists drawbacks (coupling, coarse
  versioning, open ended content, ordering, fixed provider,
  shadowing) and recommends Import-Package where possible.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@stbischof
stbischof requested a review from tjwatson November 4, 2026 16:48
@stbischof

stbischof commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

@tjwatson @timothyjward @maho7791

Do we all agree that this just explains the spec better and does not change the spec in any way?

If so i would merge this next spec meeting 18.11.2026

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants