The project was recently switched to using a "trunk-based" development strategy. This necessitated some adjustments to
the configuration of the GitHub Actions workflows in order to ensure the CI system could be used to effectively validate
the project at the state staged for release in the release branch.
A `run-determination` job was added to the workflow. This job determines whether the conditions under which the workflow
was triggered indicate that the rest of the jobs in the workflow should be run.
A validation workflow should run fully under any of the following conditions:
- The trigger event was something other than a branch creation
- The trigger event was a release branch creation
Since the project is fully validated prior to a release, running the workflow when triggered by a release tag is
pointless (and even harmful in some specific standardized workflows not currently used in this repository), so (even if
for no other reason than efficiency) verification workflows are configured to not run under these conditions.
The standardized Arduino tooling workflows follow a modular design where each workflow has a narrow scope of purpose.
That path was not taken by those who set up the infrastructure for this repository. They instead created a single
massive monolithic "Arduino IDE" workflow that performs many unrelated operations under various conditions. This workflow generates
releases in addition to doing validation. Even though it is pointless to run the workflow's validation operations when
the workflow is triggered by a release tag, it is essential to run it for the release generation.
Previously, the code used in the "Arduino IDE" workflow's `run-determination` job was configured as appropriate for a
verification workflow. This meant that a release would not be generated on push of a release tag as intended. The bug is
fixed by adjusting the code to do a full run of the workflow when triggered by a release tag.
- update Theia to `1.39.0`,
- remove the application packager and fix the security vulnerabilities,
- bundle the backed application with `webpack`, and
- enhance the developer docs.
Co-authored-by: Akos Kitta <a.kitta@arduino.cc>
Co-authored-by: per1234 <accounts@perglass.com>
Signed-off-by: Akos Kitta <a.kitta@arduino.cc>
Previously, releases were always made from a point in the revision history of the `main` branch (typically the tip of
the branch at the time of the release). Although the simplicity of this approach is nice, it can be limiting in some
cases. For this reason, the project is switching to using a "trunk-based" development strategy, as described here:
https://trunkbaseddevelopment.com/
This approach allows making releases at any time that consist of the arbitrary subset of revisions suitable for shipping
to the users at that time. The commits that should be included in the release are cherry-picked to a release branch and
the tag created on that branch.
This means that:
- PRs can be merged to the `main` branch as soon as they have passed review rather than having to postpone the merge of
changes that are not ready to be included in the next release.
- Releases don't need to be postponed if the prior revision history on the `main` branch contains changes that are not
ready to be included in the release.
The documented release procedure must be adjusted to reflect the new development strategy.
CI System Adjustments
---------------------
The status of the GitHub Actions workflows should be evaluated before making a release. However, this is not so simple as
checking the status of the commit at the tip of the release branch. The reason is that, for the sake of efficiency, the
workflows are configured to run only when the processes are relevant to the trigger event (e.g., no need to run unit
tests for a change to the readme).
In the case of the default branch, you can simply set the workflow runs filter to that branch and then check the result
of the latest run of each workflow of interest. However, that was not possible to do with the release branch since it
might be that the workflow was never run in that branch. The status of the latest run of the workflow in the default
branch might not match the status for the release branch if the release branch does not contain the full history.
For this reason, it will be helpful to trigger all relevant workflows on the creation of a release branch. This will
ensure that each of those workflows will always have at least one run in the release branch. Subsequent commits pushed to
the branch can run based on their usual trigger filters and the status of the latest run of each workflow in the branch
will provide an accurate indication of the state of that branch.
Branches are created for purposes other than releases, most notably feature branches to stage work for a pull request.
Due to the comprehensive nature of this project's CI system, it would not be convenient or efficient to fully run all CI
workflows on the creation of every feature branch.
Unfortunately, GitHub Actions does not support filters on the `create` event of branch creation like it does for the
`push` and `pull_request` events. There is support for a `branches` filter of the `push` event, but that filter is an
"AND" to the `paths` filter while this application requires an "OR". For this reason, the workflows must be triggered by
the creation of any branch. The unwanted job runs are prevented by adding a `run-determination` job with the branch
filter handled by Bash commands. The other jobs of the workflow use this `run-determination` job as a dependency, only
running when it indicates they should via a job output. Because this minimal `run-determination` job runs very quickly,
it is roughly equivalent to the workflow having been skipped entirely for non-release branch creations.
- Updated `@theia/*` to `1.37.0`.
- Fixed all `yarn audit` security vulnerabilities.
- Updated to `electron@23.2.4`:
- `contextIsolation` is `true`,
- `nodeIntegration` is `false`, and the
- `webpack` target is moved from `electron-renderer` to `web`.
- Updated to `typescript@4.9.3`.
- Updated the `eslint` plugins.
- Added the new `Light High Contrast` theme to the IDE2.
- High contrast themes use Theia APIs for style adjustments.
- Support for ESM modules: `"moduleResolution": "node16"`.
- Node.js >= 16.14 is required.
- VISX langage packs were bumped to `1.70.0`.
- Removed undesired editor context menu items. (Closes#1394)
Signed-off-by: Akos Kitta <a.kitta@arduino.cc>
Arduino IDE offers an update to the user when a newer version is available. The availability of an update is determined
by comparing the user's IDE version against data file ("channel update info file") stored on Arduino's download server.
These "channel update info files" are automatically generated by the build workflow.
Previously the release process was fully automated, including the upload of the "channel update info files" to the
server.
As a temporary workaround for limitations of the GitHub Actions runner machines used to produce the automated builds,
some release builds are now produced manually:
- Linux build (because the Ubuntu 18.04 runner was shut down and newer runner versions produce builds incompatible with
older Linux versions)
- macOS Apple Silicon build (because GitHub hosted Apple Silicon runners are not available)
The automatic upload of the "channel update info files" produced by the build workflow is problematic because if users
receive update offers before the "channel update info files" are updated for the manually produced builds, they can
receive an update to a different build than intended:
- Users of older Linux versions would update to a build that won't start on their machine
- macOS Apple Silicon users would update to macOS x86 build that is less performant on their machine
For this reason, the build workflow is adjusted to no longer upload the Linux and macOS "channel update info files" to
the download server on release. These files will now be manually uploaded after they have been updated to provide the
manually produced builds.
This workaround will be reverted once a fully automated release system is regained.
- updated to `electron-builder@23.6.0`
- set `CSC_FOR_PULL_REQUEST` env to run notarization for a PR build.
Signed-off-by: Akos Kitta <a.kitta@arduino.cc>
The "Check Certificates" GitHub Actions workflow uses OpenSSL to check for problems with the project's signing
certificates.
Certificates exported to PKS#12 archive files using older tools may have been encrypted using the "RC2-40-CBC"
algorithm.
Due to the availability of more secure modern alternatives, default support for RC2-40-CBC encryption was dropped in
OpenSSL 3.x.
The macOS signing certificate uses this RC2-40-CBC encryption.
The "Check Certificates" GitHub Actions workflow runs on the `ubuntu-latest` runner. Previously, this runner used Ubuntu
20.04. This has now changed to Ubuntu 22.04. With the operating system update came an OpenSSL update from 1.1.1f to
3.0.2. This caused the workflow runs to fail on the macOS certificate job:
Error outputting keys and certificates
80FBB0C5087F0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:../crypto/evp/evp_fetch.c:349:Global default library context, Algorithm (RC2-40-CBC : 0), Properties ()
Even though no longer done by default, OpenSSL still supports RC2-40-CBC encryption via its "legacy" provider. So
compatibility with the certificate is restored by adding the `-legacy` flag to the `openssl pkcs12` commands.
The "Arduino IDE" GitHub Actions workflow generates a changelog from the commits since the last tag.
This changelog is published in multiple ways:
- Printed to workflow run logs
- Uploaded to Arduino's download server (mostly useful for the nightly builds)
- Initial version of release notes
For the last, the changelog text must be passed from the dedicated changelog generation workflow step to the release
step. This is done via workflow job output.
At the time the system was set up, outputs for workflow `run` steps were set using the `set-output` workflow command.
That "workflow command" system was later determined by GitHub to have potential security vulnerabilities, so it was
replaced with a `GITHUB_OUTPUT` environment file.
The "Arduino IDE" workflow was migrated to the new "environment file" approach. It was later discovered that there was
an undocumented breaking change in the method for handling multi-line strings in workflow step outputs between the old
"workflow command" system and the new "environment file". This resulted in the initial release notes having an incorrect
format. For example, what would previously have been formatted like this:
- Updated translation files (#1606) [23c7f5f]
- Use 0.29.0 CLI in IDE2 (#1683) [f1144ef]
Was now formatted like this:
- Updated translation files (#1606) [23c7f5f]%0A - Use 0.29.0 CLI in IDE2 (#1683) [f1144ef]%0A
The solution is to remove the commands that did the escaping of the changelog text in a manner that is no longer
supported and replace them with a "here document"-style format.
A random number is used as the "delimiter" (limit string) per the security recommendations in the official GitHub
documentation. Note that even though the multiline strings handling documentation was placed under the environment
variable section, it also applies to setting outputs.
The issue forms are configured to request the contributor to test using the nightly build of Arduino IDE before
submitting an issue in order to make sure the bug or feature request has not already been resolved.
Some time ago, the repository's readme contained a table of download links. The links in the issue forms pointed there.
That table was replaced with a link to the official "Software" page in order to reduce unnecessary verbosity and
maintenance burden of the project's documentation content.
The issue form links were not updated at that time. The resulting additional link in the chain made obtaining the
nightly build less convenient for the contributor to obtain.
The links are hereby updated to point directly to the list of nightly build download links on the arduino.cc "Software"
page.
GitHub Actions provides the capability for workflow authors to use the capabilities of the GitHub Actions ToolKit
package directly in the `run` keys of workflows via "workflow commands". One such command is `set-output`, which allows
data to be passed out of a workflow step as an output.
It has been determined that this command has potential to be a security risk in some applications. For this reason,
GitHub has deprecated the command and a warning of this is shown in the workflow run summary page of any workflow using
it:
The `set-output` command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more
information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/
The identical capability is now provided in a safer form via the GitHub Actions "environment files" system. Migrating
the use of the deprecated workflow commands to use the `GITHUB_OUTPUT` environment file instead fixes any potential
vulnerabilities in the workflows, resolves the warnings, and avoids the eventual complete breakage of the workflows that
would result from GitHub's planned removal of the `set-output` workflow command 2023-05-31.
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.
