Clarification needed on supported Ruby versions

[ska...@gmail.com]

Hi there!

It is quite unclear on which Ruby versions Yard is supposed to run on.

1. README says nothing.

2. CHANGELOG says that support for Ruby < 2.0 has been removed on January 2017, nevertheless bug fixes for older Rubies are still accepted.

3. In CI, Yard is tested against Ruby 2.2 and newer.

These discrepancies lead to following problems:

1. I, as a contributor, am unsure which Ruby version I should target for, and which language or stdlib features I can use.

2. It is possible that Yard is not tested in CI against some of the supported Ruby versions.

3. There are plenty of Ruby-1.8-related hacks and patches in the code base, which are not even covered in CI properly.

Therefore, a clarification on supported Ruby versions is needed. I believe that this information should be clearly stated in README. Also, ".travis.yml" should be updated, if needed. Moreover, I propose to explicitly drop support for the very oldest Ruby versions in the next non-patch-level release, which will allow to gradually remove hacks and patches since then.

Finally, I want to say that it probably doesn't matter that much which Ruby version Yard is running on, because documentation for Ruby-1.8-compatible programs can be produced by Yard running on Ruby 2.5 (I guess). At least in the HTML format.

Regards,

Sebastian

[Loren Segal]

On 10/2/2018 12:46 PM, ska...@gmail.com wrote:
> Hi there!
>
> It is quite unclear on which Ruby versions Yard is supposed to run on.
>
> 1. README says nothing.
> 2. CHANGELOG says that support for Ruby < 2.0 has been removed on
> January 2017, nevertheless bug fixes for older Rubies are still accepted.
> 3. In CI, Yard is tested against Ruby 2.2 and newer.

YARD explicitly supports Ruby 2.0+ and unofficially supports Rubies
prior to 2.0 through user provided patches. The goal is to provide as
much value to as many users of Ruby as possible. For that reason, you
can consider YARD to be expected to work on all Rubies. If someone wants
to contribute or improve support on Ruby X.Y.Z via PR, it would be
considered.

>
> These discrepancies lead to following problems:
>
> 1. I, as a contributor, am unsure which Ruby version I should target
> for, and which language or stdlib features I can use.

You should use the minimal set of functionality available as of Ruby
2.0. Practically speaking this shouldn't really affect you, since YARD
doesn't rely on many stdlib features outside of core (non-requirable)
classes, and those tend to not change as often, +/- new Array enumerator
types, which are usually not needed. If this does come up code review is
where it would be raised, and, of course, CI tests.

To make this less abstract: if a contributor has a strong use case for
an stdlib feature that was only introduced in, say, Ruby 2.3, that's a
discussion we could have in a code review. I think this has come up once
or twice before and we've always found paths forward. Again, you
shouldn't need to worry too much about this initially, focus on writing
the best patch and allow the code review / CI testing process to
identify (and fix) any potential compat issues.

> 2. It is possible that Yard is not tested in CI against some of the
> supported Ruby versions.

I believe we go all the way back to 2.2, which should be sufficient
coverage, realistically. I'd be ok with adding support all the way back
to 2.0 since it seems like Travis still runs those Rubies.

> 3. There are plenty of Ruby-1.8-related hacks and patches in the code
> base, which are not even covered in CI properly.

This is fine since 1.8/1.9 are no longer explicitly supported in core.
Users are free to test changes in YARD and submit patches if they find
issues (which would probably be accepted provided they are scoped to
those versions), but that kind of testing / bug catching support won't
come from core development. If someone wanted to, they could create a
mirror repository of YARD that runs CI against older Rubies, but this
has never come up.

>
> Therefore, a clarification on supported Ruby versions is needed. I
> believe that this information should be clearly stated in README.
> Also, ".travis.yml" should be updated, if needed. Moreover, I propose
> to explicitly drop support for the very oldest Ruby versions in the
> next non-patch-level release, which will allow to gradually remove
> hacks and patches since then.

There's no plan to remove hacks and patches unless we make a major
version change to YARD, since removing code would break existing
installs. There are currently no plans to major version bump YARD just
for this reason.

>
> Finally, I want to say that it probably doesn't matter that much which
> Ruby version Yard is running on, because documentation for
> Ruby-1.8-compatible programs can be produced by Yard running on Ruby
> 2.5 (I guess). At least in the HTML format.

This is true for some use cases but not all. Many users rely on YARD at
runtime of other libraries and applications that may have older
dependency requirements. Not every end-user is capable of easily running
on Ruby 2.5, even in out-of-band tooling.

The amount of effort required to support older Ruby versions is much
smaller than the amount of effort a user in a legacy toolchain would
need to exert to use YARD, so based on that equation, it's worth
supporting those users.

Loren

[ska...@gmail.com]

Thanks for your response. It answers all my questions in detail.

IMO if Yard is supposed to support Ruby 2.0, then respective Travis builds are needed. I've noticed your attempt to enable them.

Sebastian

[ska...@gmail.com]

Albeit I fully accept above explanaition, I need to say that in my so

far very few contributions to Yard, I already had at least two

situations when 1.8 core lib was lacking important features.  First one

is related to encoding, the other one to regular expressions.  Both have

been rehauled in 1.9, and are core features.