Skip to content

building-and-testing-ruby.md - remove wildcard, version, clarify x.0 #13418

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.

Sign up for GitHub

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

Closed
dentarg wants to merge 1 commit into from
Closed

building-and-testing-ruby.md - remove wildcard, version, clarify x.0 #13418

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions content/actions/automating-builds-and-tests/building-and-testing-ruby.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ jobs:

## Specifying the Ruby version

The easiest way to specify a Ruby version is by using the `ruby/setup-ruby` action provided by the Ruby organization on GitHub. The action adds any supported Ruby version to `PATH` for each job run in a workflow. For more information see, the [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby).
The easiest way to specify a Ruby version is by using the `ruby/setup-ruby` action provided by the Ruby organization on GitHub. The action adds any supported Ruby version to `PATH` for each job run in a workflow. For more information and available Ruby versions, see [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby).

Using Ruby's `ruby/setup-ruby` action is the recommended way of using Ruby with GitHub Actions because it ensures consistent behavior across different runners and different versions of Ruby.

Expand All @@ -87,13 +87,13 @@ Alternatively, you can check a `.ruby-version` file into the root of your repos

## Testing with multiple versions of Ruby

You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 2.7, 2.6, and 2.5. The 'x' is a wildcard character that matches the latest patch release available for a version.
You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 3.0, 2.7, and 2.6. YAML parsers will truncate trailing zeros from numeric values, and often convert floats to integers. So, an unquoted 3.0 is converted to an integer, so it will match any minor version, as in 3.0.3, 3.1.0, etc. Likewise, 2.10 needs to be quoted, otherwise it will be interpreted as 2.1.
Copy link
Contributor Author

@dentarg dentarg Dec 27, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 3.0, 2.7, and 2.6. YAML parsers will truncate trailing zeros from numeric values, and often convert floats to integers. So, an unquoted 3.0 is converted to an integer, so it will match any minor version, as in 3.0.3, 3.1.0, etc. Likewise, 2.10 needs to be quoted, otherwise it will be interpreted as 2.1.
You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 3.0, 2.7, and 2.6. The YAML parser used by GitHub Actions will truncate trailing zeros from numeric values, and often convert floats to integers. So, an unquoted 3.0 is converted to an integer, so it will match any minor version, as in 3.0.3, 3.1.0, etc. Likewise, 2.10 needs to be quoted, otherwise it will be interpreted as 2.1.

It is good that we document this gotcha, but it sounds like it is a bug that should be addressed: actions/runner#849 (comment)

Copy link

@MSP-Greg MSP-Greg Dec 28, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IDK. The text I wrote was meant to not be specific, as most coders would prefer [3.0, 2.7, 2.6] to ['3.0', '2.7', '2.6']. Each item is really an array match to a version string (split into an array), which isn't a number (ie, major.minor.patch, or 3.0.1, worse with alphas, betas, rc's, etc). Hence, I wanted to make readers aware of it without implying a yaml parser is working incorrectly. Not the best explanation, but...

off-topic: For people who don't code Ruby, it's a non-typed language, but 1/3 = 0 and 1/3.0 = 0.333...
Hence, Ruby considers 3 to be an int, and 3.0 to be a float. So, Ruby's default yaml parser considers 3 to be an int, and 3.0 to be a float.

Copy link
Contributor

@ethomson ethomson Feb 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coders may prefer [3.0, 2.7, 2.6] for simplicity, but those aren't numbers, they're strings and they should be quoted. Otherwise you will run into exactly the problem that you describe where 2.10 needs to be quoted to disambiguate from 2.1. I would illustrate the happy path in the doc and then explain why you've quoted all the version numbers instead of trying to tell people when they need to quote.

Copy link

@MSP-Greg MSP-Greg Feb 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ethomson

Thanks. I don't know what's best in this doc, but there are a lot of workflows in the wild that only quote what is needed, ie '3.0'. So, I wanted some background on why... Also, see #15240

Copy link
Contributor

@ethomson ethomson Feb 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense @MSP-Greg. I think that it's safe to say that mine is an unpopular opinion, so I'd like to give some time to give others a chance to provide feedback, but I think that we should encourage users to quote version numbers and ensure that the starter workflows follow our guidance here.

Copy link
Contributor

@skedwards88 skedwards88 Feb 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coders may prefer [3.0, 2.7, 2.6] for simplicity, but those aren't numbers, they're strings and they should be quoted.

I agree with this. The semantic version isn't actually a number, it just works in some cases to treat it as such. Although people often leave out the quotes, we try to craft examples in the docs that illustrate best practices and that will work if users copy-paste-edit without being aware of nuances like this.

@dentarg opened a PR that does this: #15240


{% raw %}
```yaml
strategy:
matrix:
ruby-version: [2.7.x, 2.6.x, 2.5.x]
ruby-version: ['3.0', 2.7, 2.6]
```
{% endraw %}

Expand All @@ -119,7 +119,7 @@ jobs:

strategy:
matrix:
ruby-version: [2.7.x, 2.6.x, 2.5.x]
ruby-version: ['3.0', 2.7, 2.6]

steps:
- uses: actions/checkout@v2
Expand Down Expand Up @@ -225,7 +225,7 @@ jobs:
fail-fast: false
matrix:
os: [ubuntu, macos]
ruby: [2.5, 2.6, 2.7, head, debug, jruby, jruby-head, truffleruby, truffleruby-head]
ruby: [2.6, 2.7, '3.0', head, debug, jruby, jruby-head, truffleruby, truffleruby-head]
continue-on-error: {% raw %}${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}{% endraw %}
steps:
- uses: actions/checkout@v2
Expand Down