Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Improve task parameter environment variable documentation #934

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.

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

Merged
per1234 merged 3 commits into arduino:main from per1234:task-param-docs
Sep 11, 2025

Conversation

Copy link
Contributor

@per1234 per1234 commented Sep 11, 2025

Some tasks accept input via environment variables. It is important to document these parameter variables.

Previously, the parameter environment variables of these tasks were undocumented, or documented in an non-standard manner.

Some tasks accept input via environment variables. It is important to document these parameter variables.
Previously, the parameter environment variables of these tasks were undocumented.
Typically, the documentation is done in the task description, to make the information easily accessible to contributors
via the `task list` output. However, this approach was intentionally eschewed in the case of the `yaml:lint` task, where
the documentation was instead placed in a comment. The reason is that this task's parameter variable is only useful when
the task is executed by a GitHub Actions workflow, as is done already in the "Check YAML" workflow. So the contributor
running the task from the command line has no need for this information and thus including it in the description would
only clutter up the `task list` output with content useless to the reader of that output.
Tasks are provided to perform common project development and maintenance operations. Some of these tasks are configured
by setting an environment variable from the invocation. It will be important for the contributor to be aware of these
variables when using the task directly (as opposed to via the "umbrella" convenience functions which set the variables
as appropriate for the project).
Previously, when done at all, the variables where documented in comments in the taskfile. The contributor would only see
that information if they looked at the source content of the taskfile, but a contributor would only be expected to do
that if they were working on the taskfile source. The documented way for a contributor to learn about the available
tasks is by running the `task --list` command. This displays the contents of the task's `desc` field. So the parameter
variables must be documented in that field.
Some tasks accept input via environment variables. These parameter variables are documented in the task description.
A standard format has been established for that documentation. Previously, these descriptions did not follow the
standardized format.
Typically, the documentation is done in the task description, to make the information easily accessible to contributors
via the `task list` output. However, a description was intentionally omitted for these tasks. The reason is these tasks
are for internal use by other tasks, only serving to avoid code duplication. So the tasks should not be listed in the
`task list` output. Task actually has a feature for marking such tasks as internal, but unfortunately that only works
for the standard way of calling a task from another task, which can not be used in this case where the output of the
task must be captured. For this reason, the task documentation is intentionally done via a comment instead of the
description as would be done for a contributor facing task.
@per1234 per1234 self-assigned this Sep 11, 2025
@per1234 per1234 added type: enhancement Proposed improvement topic: infrastructure Related to project infrastructure labels Sep 11, 2025
Copy link

codecov bot commented Sep 11, 2025
edited
Loading

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.33%. Comparing base (2affc92) to head (a29f6f5).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files
@@ Coverage Diff @@
## main #934 +/- ##
=======================================
 Coverage 83.33% 83.33% 
=======================================
 Files 1 1 
 Lines 180 180 
=======================================
 Hits 150 150 
 Misses 19 19 
 Partials 11 11 
Flag Coverage Δ
unit 83.33% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@per1234 per1234 merged commit 4de008f into arduino:main Sep 11, 2025
58 of 70 checks passed
@per1234 per1234 deleted the task-param-docs branch September 11, 2025 23:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Labels
topic: infrastructure Related to project infrastructure type: enhancement Proposed improvement
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

1 participant

AltStyle によって変換されたページ (->オリジナル) /