Demonstrate usage in multi-board coverage applications #84
Conversation
This file contains 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
Some GitHub Actions workflows are provided in the readme to demonstrate the use of the action. These workflows have dependencies on the "actions/upload-artifact" and "actions/download-artifact" actions. Previously, these dependencies were pinned to their 3.x major version series. A 4.x major version series of the actions was recently started. It is best practices to use the latest version of actions, so the documentation should demonstrate that. A significant breaking change was introduced in the 4.0.0 release of "actions/upload-artifact": uploading multiple times to the same artifact is no longer allowed. Previously the "Workflow triggered by `pull_request` event" example workflow used a single artifact for the sketches report file produced by the matrix job for each of the boards the sketches were compiled for. It was necessary to adjust the configuration of the workflow to use a separate workflow for each of the sketches report files in order to accommodate the bump fo the "actions/upload-artifact" action dependency.
per1234
added
topic: documentation
The readme contains a set of workflows demonstrating the use of the action in the use case where the report workflow is triggered by a `schedule` event. These workflows demonstrate the most simple use case, where sketches are only being compiled for a single board. Although this provides a good introduction into using the action, the action user will often want the system to provide coverage for multiple boards. The configuration of the workflows become significantly more complex, especially now that it is necessary to upload each sketches report to a separate artifact. It will be beneficial to also demonstrate that advanced usage. The demonstration consists of a significant amount of content so putting it in the readme would harm the readability and approachability of that document. For this reason, it is published in a separate document which is linked to from the readme. This "FAQ" document will serve as a container for the addition of more supplemental documentation in the future.
A demonstration workflow is provided in the readme to show how to use the action in the use case where the report workflow is triggered by `pull_request` event. Previously, this workflow demonstrated the more advanced configuration that is required in order to compile for multiple boards. Although this demonstration will be useful to the action users, it might be overwhelming as an introduction to the action usage. A demonstration that only compiles for a single board can be far more simple. Even if the user requires coverage of multiple boards in their application, this will give them a basic understanding of the action usage. The advanced demonstration workflow is hereby moved to the FAQ document, replaced in the readme by a simple demonstration workflow. A link from the readme to the advanced usage demonstration is provided.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
The readme contains a set of workflows demonstrating the use of the action.
The action user will often want the system to provide coverage for multiple boards. The configuration of the workflows required for that use case is significantly more complex, especially now that it is necessary to upload each sketches report to a separate artifact. It will be beneficial to demonstrate that advanced usage in addition to the simplified demonstrations.
The demonstrations consist of a significant amount of content so putting them in the readme would harm the readability and approachability of that document. For this reason, they are published in a separate document which is linked to from the readme. This "FAQ" document will serve as a container for the addition of more supplemental documentation in the future.