The "github-stats" GitHub Actions workflow periodically gathers GitHub release asset download statistics for Arduino CLI
and pushes the results to Datadog.
There are no known problems with this workflow. However, the companion "arduino-stats" workflow that did the same for
the downloads of Arduino IDE from downloads.arduino.cc was broken and thus removed from the repository.
The GitHub stats are not very valuable on their own as they only provide an unknown fraction of the total downloads of
Arduino IDE. They have also not ended up being used.
The workflow also uses deprecated Node.js 12 runtime, which currently results in warnings printed to the workflow run
summary page, but will eventually cause the complete breakage of the workflow.
Since it doesn't provide any value and represents a maintenance burden, the workflow is hereby removed from the
repository.
The "arduino-stats" GitHub Actions workflow was designed to periodically gather download statistics from Arduino CDN and
push results to Datadog.
The recorded stats from the identical system in the Arduino CLI repository showed a periodic decrease in total download
count. Since this is patently impossible, it is clear that something is wrong with the system and that the recorded data
is not trustworthy. An investigation into the problem
was never done.
On 2022-03-14, the runs of the "arduino-stats" GitHub Actions workflow began to fail. Because there had not been any
relevant change in the repository between the last successful run and the first failing run, it seems that some external
change caused the breakage.
The workflow also uses deprecated Node.js 12 runtime-based actions and set-output workflow command, which currently
results in warnings printed to the workflow run summary page, but will eventually cause the complete breakage of the
workflow.
Since the workflow was not ever working successfully and the lack of an investigation about that indicates that the
stats are not of immediate importance, the best course of action is to simply remove the broken infrastructure from the
repository rather than investing time into fixing something that isn't being used anyway.
Dependabot will periodically check the versions of all actions used in the repository's workflows. If any are found to
be outdated, it will submit a pull request to update them.
NOTE: Dependabot's PRs will occasionally propose to pin to the patch version of the action (e.g., updating
`uses: foo/bar@v1` to `uses: foo/bar@v2.3.4`). When the action author has provided a major version ref, use that instead
(e.g., `uses: foo/bar@v2`). Dependabot will automatically close its PR once the workflow has been updated.
More information:
https://docs.github.com/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
Contributor are presented with an issue template chooser page at the start of the issue creation process.
In addition to the issue report templates, some "contact links" provide information and links to other communication
channels. In order to encourage high quality issues, a link to the "issue report guide" is included on this page.
Previously that link pointed to an incorrect URL, resulting in a 404 error for those who visited it. The URL is hereby
corrected.
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing the
maintenance effort and increasing the quality of contributions.
This guide documents the various ways of contributing to the project.
Arduino CLI is a tool dependency of Arduino IDE. For this reason, the necessary Arduino CLI build is acquired whenever
running the `yarn` command in the repository.
The way the Arduino CLI build is acquired depends on the type of version specified as dependency in the
`arduino.cli.version` field of the arduino-ide-extension package metadata:
- Release/nightly: download pre-built standard distribution
- Git ref: build from source
This means that, in the latter case, all build dependencies of Arduino CLI must be present. While the Go module
dependencies are automatically installed during the build, the build tool dependencies must be installed in advance:
- Go programming language
- Task task runner
Arduino IDE's infrastructure was recently changed to use the Task tool to build Arduino CLI in the supported manner. A
step to install Task was not added to some of the workflows that run `yarn`, which caused them to fail when a
non-release version of Arduino CLI was used as a dependency:
arduino-ide-extension: >>> Building the CLI...
arduino-ide-extension: /bin/sh: 1: task: not found
arduino-ide-extension: error Command failed with exit code 1.
A step for the missing tool dependency is hereby added to those workflows.
The lack of an explicit installation of the other dependency, Go did not result in an error because Go is pre-installed
on the GitHub Actions runner. However, the installed version may not match the version Arduino CLI is intended to be
built with and validated for, and the version provided by the runner may change at any time. For this reason, it will be
safest to explicitly set up the appropriate version of Go in the workflows.
The "Arduino IDE" workflow performs the following operations when triggered on push and pull request events:
- Build application
- Lint code
- Run tests
- Produce tester packages
All of these operations are specific to the TypeScript/JavaScript code base and its infrastructure.
Previously, the workflow ran whenever any file in the repository was changed. This includes files that have no
relevance, meaning the operations performed by the workflow were pointless. In addition to general inefficiency, these
lengthy and sometimes spuriously failing unnecessary workflow runs might cause delay or confusion to both the
contributors and maintainers for what would otherwise be a simple process.
GitHub Actions provides the ability to configure path filters for the workflow triggers. The workflow will only run on
events that change files satisfying these path filters. This is "AND"ed with the `branches` filters, meaning the existing
restrictions on which branches produce a run remain unchanged. The `tags` filter is independent from the `paths` and
`branches` filters, meaning the added path filters don't make any change to which tag push events will trigger the
workflow.
GitHub Actions workflows may require access to privileged information in order to perform certain operations. GitHub
provides the capability for doing this via "repository secrets".
For security reasons, repository secrets are only accessible to a GitHub Actions workflow run when it is triggered by an
event from within the repository containing the secret. This means that a workflow which requires such secrets would
fail when run in a fork (unless the fork owner was able to set up their own secrets with suitable values).
In order to make the relevant components of the CI system friendly for use in forks by contributors validating their
work in preparation for submitting a PR, when the operations that require access to a secret are supplemental, those
operations should be configured to only run from branches of the parent repository.
Due to its unfortunate monolithic design, in addition to operations useful to contributors, the "Arduino IDE" workflow
contains several such supplemental operations:
- Code signing
- Publishing release artifacts to Arduino's server
Some attempt was previously made to configure the workflow to skip these operations when run in forks, but that
configuration was not done correctly. This made the workflow only usable by contributors with a deep enough
understanding of GitHub Actions to be able to make the necessary modifications provisionally every time they needed to
use the workflow.
The average contributor would not be capable or willing to do this, which might result in PRs being
submitted in a less validated state, increasing the burden on maintainers.
The specific misconfigurations:
**`build` job was conditional on the workflow running from `arduino/arduino-ide`**
The job itself can run just fine in a fork, so there is no reason to impose this restriction.
Since the time this conditional was added, some changes have been made to the GitHub Actions system which makes this
sort of configuration unnecessary:
- GitHub Actions is globally disabled in forks by default
- Workflows which contain a `schedule` trigger (as is the case with this one) are individually disabled by default,
requiring the repository owner to enable it specifically even after enabling GitHub Actions in general.
This means this workflow will never run unexpectedly in a fork. The fork owner will always have intentionally enabled it.
So this conditional can be removed completely.
**Code signing was conditional on PR being submitted from a branch of the base repo**
This would cause a spurious failure of the signing operation on PRs made within the contributor's fork when the signing
secrets were not defined.
The more appropriate condition of whether the signing secrets are defined or not is now used. The environment variable
name has been updated accordingly.
**`release` job was conditional on running from `arduino/arduino-ide`**
The GitHub release creation step of this job can run in any repository. It is only the step that uploads to Arduino's
AWS server which would only make sense to run from `arduino/arduino-ide`.
So the conditional is moved to the AWS upload step, allowing contributors to test the workflow's release operation in
their forks to validate related proposals.
Previously, there was some code duplication of the complex code signing certificate handling commands, which made the
related code more difficult to understand, maintain, and develop.
The cause of this duplication is that there is a separate certificate for each operating system, each of which is stored
in separate repository secrets, as well as a different certificate file extension for each OS. Since the secret names
and file extensions are associated with the operating system, it is most logical to define them via attributes alongside
the operating system definition in the job matrix configuration already used to generate the parallel job runs for
native build on each OS.
That done, the certificate handling commands are universal and the system can easily expand to additional host targets
(e.g., Apple M1) as time goes on.
Contributors may submit pull requests against development branches in the repository for either of the following valid
reasons:
- Propose changes to a previous proposal, either while it is still in development, or else in the case where the changes
are more complex/extensive than can be efficiently proposed via the PR review framework.
- The proposal is dependent on work from an unmerged PR.
Previously, the "Arduino IDE" GitHub Actions workflow was unnecessarily configured to only run for PRs based on the
`main` branch. This meant that validation and tester builds were not provided for the PRs based on other branches.
GitHub issue forms are used in this repository to facilitate the creation of high quality issues. These provide input
fields for each of the distinct classes of information which will be essential for the evaluation of the issues.
One of these fields is for the user's operating system. A dropdown menu is used for the selection of the high level
operating system type. Previously this only permitted the selection of a single option. A devoted contributor might have
made the effort to determine that the issue applies to multiple operating system types only to be met with the inability
to provide this information via the dedicated field.
The field also did not offer an option to indicate that the operating system was irrelevant to the issue (e.g., a
subject related to the repository assets).
Those issues are resolved by the following changes:
- Configure the field to allow multiple selections
- Add a "N/A" option to the menu
This project provides the contributors with templates for the fundamental categories of issues:
- bug report
- feature request
This is helpful to the maintainers and developers because it establishes a standardized framework for the issues and
encourages the contributors to provide the essential information.
GitHub's original issue template system is very crude, simply pre-populating the issue description field with the text
from the template file.
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates
The contributor may be confused by being presented with a mass of Markdown and placeholder
content where they expected a field to write their issue. They also may find it inconvenient to manuever around the
framework content and replace the placeholder content.
A far better system is now available with GitHub's recently introduced form-based issue templates:
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
The user is now presented with a web form. These may include multi-line input fields that have the same formatting and
attachment capabilities as the standard GitHub Issue composer, but also additional elements such as menus and checkboxes.
The use of this form-based system should provide a much better experience for the contributors and also result in higher
quality issues.
The automatically created issue template chooser provides a menu of links to the available issue report templates as
well as the security policy at the start of the issue creation process.
It is also possible to add additional arbitrary items to the chooser, through GitHub's "Contact Links" feature. These
are defined in a configuration file:
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
These links offer the possibility to redirect support requests and other sub-optimal usages of the issues to the
appropriate location. This benefits the user by providing them with a fast and frictionless path to what they need, and
benefits the maintainers by preventing inappropriate issues.
The "Compose full changelog" GitHub Actions workflow generates a changelog file from the release notes and uploads this
to Arduino's server for display to the user by the IDE updater.
Previously, this workflow could be triggered by either of two events:
- Release creation
- Release edit
To reduce the possibility of endless recursion, GitHub Actions ignores events which are triggered using the
auto-generated `GITHUB_TOKEN` access token. All release creations are done automatically by the "Arduino IDE" GitHub
Actions workflow, which uses this token.
For this reason, the release creation trigger will never be used. Since the behavior of the event being ignored by
GitHub Actions under these conditions is not at all obvious, having the workflow configured for such an irrelevant
trigger can cause confusion.
The workflow will be triggered by the manual edit which is done on every release to format the raw release notes
auto-generated from the commit history. So the fact that the release creation trigger doesn't work is not a problem.
* IDE updater assorted bugfix
- add linux AppImage target
- fix hardcoded if condition that causes to always show the update dialog
- fix redundant test build version
- recalculate sha512 after notarization on macOS
* boost notarization speed
* recalculate artifacts hash
* Remove check for updates on startup setting
* Remove useless exported function
* Update template-package.json used to package IDE
* Add function to get channel file during packaging step
* Add updates check
* move ide updater on backend
* configure updater options
* add auto update preferences
* TMP check updates on start and download
* index on check-update-startup: fcb8f6e TMP check updates on start and download
* set version to skip on local storage
* add IDE setting to toggle update check on start-up
* comment out check for updates on startup and auto update settings
* Update Theia to 1.22.1
* updated CI
* download changelog and show it in IDE updater dialog
* remove useless file
* remove useless code
* add i18n to updater dialog
* fix i18n
* refactor UpdateInfo typing
* add macos zip to artifacts
* Simply use `--ignore-engines`
* Use correct --ignore-engines
* Fix semver#valid call
* Use C++17
* updated documentation
* add update channel preference
* update updater url
* updated documentation
* Fix the C++ version
* Build flag for cpp
* add disclaimer with correct node version
* Update `electron-builder`
* Fix `Electron.Menu` issue
* Skip electron rebuild
* Rebuild native dependencies beforehand
* Use resolutions section
* Update template-package.json as well
* move ide-updater to electron application
* refactor ide-updater service
* update yarn.lock
* update i18n
* Revert "Add gRPC user agent (#834)"
This reverts commit 5ab3a747a6e8bf551b5c0e59a98154d387e0a200.
* fix ide download url
* update latest file in CI
* fix i18n check
Co-authored-by: Silvano Cerza <silvanocerza@gmail.com>
Co-authored-by: Francesco Stasi <f.stasi@me.com>
Co-authored-by: Mark Sujew <msujew@yahoo.de>
The `carlosperate/download-file-action` action is used in the GitHub Actions workflows as a convenient way to download
external resources.
A major version ref has been added to that repository. It will always point to the latest release of the "1" major
version series. This means it is no longer necessary to do a full pin of the action version in use as before.
Use of the major version ref will cause the workflow to use a stable version of the action, while also benefiting from
ongoing development to the action up until such time as a new major release of an action is made. At that time we would
need to evaluate whether any changes to the workflow are required by the breaking change that triggered the major
release before manually updating the major ref (e.g., uses: `carlosperate/download-file-action@v2`). I think this
approach strikes the right balance between stability and maintainability for these workflows.
In order to facilitate the testing and review of proposed changes to the repository label infrastructure, the
"Sync Labels" template workflow does a dry run when triggered under conditions that indicate it would not be appropriate
to make real changes to the repository's labels. The changes that would have resulted are printed to the log, but not
actually made.
One of the criteria used to determine "dry run" mode usage is whether the event occurred on the repository's default
branch. A trigger on a development branch or for a pull request should not result in a change to the labels.
It turns out that GitHub does not define a `github.event.repository.default_branch` context item when a workflow is
triggered by a `schedule` event. This resulted in the workflow always running in "dry run" mode on a `schedule` trigger.
Since `schedule` and `repository_dispatch` triggers are only permitted for the default branch, there is no need to check
whether the event's ref matches the default branch and it is safe to always run in write mode on these events.
Incorrect context key name resulted in impossible to satisfy conditional, meaning the dry run determination code was
solely dependent on the check for whether the workflow was triggered from the default branch name.
