Release 1.0.1 cherry picks #122
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ple#111) Motivation ---------- The DoCC documentation was restructured substantially between 0.5.0 and 1.0.0, so the links in `README.md` are no longer correct. The examples should also point to the new release. Modifications ------------- * Update the links to the Swift Package Index documentation * Update example project dependencies * Stop asking SPI to build the `containertool` documentation target Result ------ Documentation links will be correct once Swift Package Index builds the new release. Test Plan --------- All existing tests continue to pass.
…e#112) Motivation ---------- By default, Swift Package Index shows the documentation for the latest release. This still has the `containertool` documentation target in `.spi.yml`, which is causing the left-hand navigation bar (the curation) to show the topics for `containertool` even though the main content is the Swift Container Plugin Documentation. This should be resolved when the next release is tagged, but in the meantime linking to the `main` branch documentation will cause users to see the most up-to-date documentation with the correct navigation bar. Modifications ------------- Links to the SPI documentation in `README.md` point to the `main` branch. Result ------ Users should see the latest documentation, with the correct navigation bar. Test Plan --------- No functional change. All existing tests continue to pass.
…geReference arguments (apple#114) Motivation ---------- `ContainerRegistry` methods follow the distribution API closely. `containertool` defines some extensions which build more convenient operations over these primitive functions. These extensions should accept `ImageReference` arguments. Currently they take separate repository and reference arguments and the caller needs to extract these fields from the appropriate references. This provides an opportunity for errors, such as trying to use the a reference with the wrong repository. Modifications ------------- `getImageManifest()`, `getImageConfiguration()` and `putImageConfiguration()` now accept `ImageReference` arguments. Result ------ The caller no longer has to extract the underlying fields, and the risk of mixing them up is reduced. Test Plan --------- All tests continue to pass.
…lishing (apple#116) Motivation ---------- Most of `containertool`'s work is handled in its `run()` method. * It starts by processing arguments and assigning defaults; * It then creates `RegistryClient` instance; * Finally it assembles the image and uploads it. All of this work takes place inline, in a single method called by `SwiftArgumentParser`. This complicates maintenance and makes it difficult to test the image assembly process without writing full end-to-end tests. Modifications ------------- * Extract the image building process into a standalone function. * `run()` is only responsible for processing arguments and creating the clients needed by the build function. Result ------ The image build process will be easier to test and maintain. It will be easier to add more complex argument handling, such as additional environment variables or a configuration file. Test Plan --------- Existing tests continue to pass. Future pull requests can test the image build process in integration or unit tests, instead of requiring full end-to-end tests.
…le#117) Motivation ---------- Many `containertool` options have default values set by environment variables. * if the option flag is set on the command line, the command line value is used * otherwise, if the option flag is not set, the environment variable value is used * otherwise, a hard-coded default is used This pattern is quite convenient, but there are some drawbacks. For example: * the default value declarations complicate the definition of new arguments. * default values appear in the `--help` output: for some options, such as default base image, this is desirable, but for others, such as credentials, it is not. Some options do not fit this pattern well. For instance, `containertool` tries to detect the architecture of the executable it is packaging so it can try to choose a compatible base image. * if the architecture flag is set on the command line, that value is used * otherwise, if the flag is not set, the environment variable value is used * otherwise, if the executable is an ELF file, the architecture is read from the file * otherwise, a hard-coded default is used The path to the executable is an option which is parsed by the argument parser. It is not available when the parser sets up default argument values, so it must be handled after the arguments have been parsed, overwriting whatever the parser had set. This means that option handling for this flag is split into two different places, which invites bugs. Future changes to `containertool`'s configuration, such as supporting a configuration file on disk, add further complications. Modifications ------------- * All command line arguments with corresponding environment variables are handled uniformly, with defaults applied at the start of the `run()` function Result ------ No functional change, but maintenance and future enhancement become easier. Test Plan --------- All existing tests continue to pass. Handling defaults in this way allows future PRs to add unit or integration tests which exercise argument parsing.
Motivation ---------- On first visit to the repository or the documentation, it can be difficult to understand what the plugin does and how it fits into the development process. A flow diagram showing how the code is built, packaged, uploaded and deployed is much easier to read at a glance than a screen of example command output. The diagram can also provide a structure which can be referred to in the text. Modifications ------------- * Add a workflow diagram image * Rewrite the overview section of README.md and the DocC documentation entry point to include the image and expand on what happens in each step. Result ------ New visitors to the repository or the documentation will see a diagram which summarises what the plugin does and where it fits in the Swift Package Manager workflow. Test Plan --------- All existing tests continue to pass. Manually tested all new URLs.
Motivation ---------- The help text for `--username` and `--password` states that these options override `.netrc`. In fact they are used as defaults if no suitable entry is found in `.netrc`. Modifications ------------- Correct the `--help` option descriptions and manual page. Result ------ Help and documentation accurately describe what the options do. Test Plan --------- All existing tests continue to pass. No functional change.
euanh
added
area/documentation
euanh
added
the
kind/cherry-pick
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Some minor documentation bugs have been fixed on
main. We would like to release these changes and point the Swift Package Index documentation links back at the most recent release (#113), but some minor changes for v1.1 are also in main. This pull request cherry-picks only the patch changes.Modifications
Cherry picks:
#111
#112
#114
#116
#117
#120
#121
Result
release/1.0will hold only patch-level fixes suitable for a 1.0.1 release.Test Plan
All existing tests continue to pass.