Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the stack specification format and output tagging #78

Open
ncoghlan opened this issue Nov 8, 2024 · 1 comment
Open

Document the stack specification format and output tagging #78

ncoghlan opened this issue Nov 8, 2024 · 1 comment
Assignees
@ncoghlan
Labels
Affects: Metadata Affects the stack output metadata Affects: Spec Format Affect the stack specification format Category: Documentation Improvements or additions to documentation

Comments

@ncoghlan
Copy link
Collaborator

ncoghlan commented Nov 8, 2024

With automatic layer versioning fixed in #64, we need explanatory documentation that covers the trade-offs between setting versioned=true on a layer and appending @NNN manually to the layer names (there are specific reasons that the automatic versioning is an opt-in feature, mostly around the fact that it means that any update to that layer always requires republishing the layers that depend on it, even if nothing the upper layer uses actually changed).

There's no good place to put that information in the initial version of the docs, so the best way to handle is to actually add the missing documentation for the stack specification format and the way it relates to the --tagged-output setting when publishing artifacts.
@ncoghlan ncoghlan self-assigned this Nov 8, 2024
@ncoghlan ncoghlan added Category: Documentation Improvements or additions to documentation Affects: Metadata Affects the stack output metadata Affects: Spec Format Affect the stack specification format labels Nov 8, 2024
ncoghlan added a commit that referenced this issue Nov 11, 2024
@ncoghlan
Initial documentation for venvstacks.toml
16c7d22 
* Add new docs page for file format details
* Check release note snippets when building docs
* Allow single backtick for inline literals in docs (and docstrings)
* Add OpenGraph metadata for more pages
* Fail the docs build on warnings
* Allow passing args to the docs build when running locally

Initial steps towards #78
@ncoghlan ncoghlan mentioned this issue Nov 11, 2024
Merged
ncoghlan added a commit that referenced this issue Nov 12, 2024
@ncoghlan
Initial documentation for venvstacks.toml (#82)
7877f74 
* Add new docs page for file format details
* Check release note snippets when building docs
* Allow single backtick for inline literals in docs (and docstrings)
* Add OpenGraph metadata for more pages
* Fail the docs build on warnings
* Allow passing args to the docs build when running locally

Initial steps towards #78
@ncoghlan
Copy link
Collaborator Author

Explicitly documenting this also resulted in some format changes for the specification and layer metadata:

  • fully_versioned_name in runtime layer specs is now implementation_name (old name is still accepted, but emits FutureWarning)
  • the obsolete-since-Drop implicit build support #6 build_requirements field now emits FutureWarning when used
  • runtime_name in the output metadata now always refers to the runtime installation target directory
  • new implementation_name and bound_to_implementation fields have been added to the layer output metadata

ncoghlan added a commit that referenced this issue Nov 12, 2024
@ncoghlan
Discourage use of @ in layer names
9570404 
* Updated docs to actively discourage using ``@`` in layers names
* Rename "explicitly versioned" to "externally versioned", and make it
  clear that is a separate concept from implicit layer lock versioning
* Rename `fully_versioned_name` runtime layer spec field to `implementation_name`
* Simplified ``runtime_name`` in layer metadata to always refer to the runtime install target
* Added `implementation_name` to the published layer metadata
* Added `bound_to_implementation` to the published layer metadata
* Add mechanism to emit `FutureWarning` for renamed and removed spec
  fields (which still accepting them)

Continues work on #78
@ncoghlan ncoghlan mentioned this issue Nov 12, 2024
Merged
ncoghlan added a commit that referenced this issue Nov 14, 2024
@ncoghlan
Discourage use of @ in layer names (#84)
547c860 
* Updated docs to actively discourage using ``@`` in layers names
* Updated test cases to follow the docs guidance
* Renamed "explicitly versioned" to "externally versioned", and made it
  clear that is a separate concept from implicit layer lock versioning
* Dropped obsolete `build_requirements` layer spec field
* Renamed `fully_versioned_name` runtime layer spec field to `python_implementation`
* Renamed `runtime_name` to `runtime_layer` in layer metadata and simplified it
  to always refer to the runtime install target
* Added `python_implementation` to the published layer metadata
* Added `bound_to_implementation` to the published layer metadata
* Added mechanism to emit `FutureWarning` for renamed and removed spec
  fields (while still accepting them)
* Added new stack spec loading test cases for above changes (including one
  that confirms using `@` in layer names still works for both unversioned and
  implicitly versioned layers)

Continues work on #78
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ncoghlan ncoghlan

Labels
Affects: Metadata Affects the stack output metadata Affects: Spec Format Affect the stack specification format Category: Documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@ncoghlan