+1 for using {{site.release_latest}}, which is make more sense to me.
Best,
Jincheng
Kenneth Knowles <[email protected]> 于2019年12月11日周三 下午1:12写道：
> +1 to site.release_latest
>
> We do have a dead link checker in the website tests. Does it not catch
> moved classes, etc?
>
> On Tue, Dec 10, 2019 at 1:49 PM Pablo Estrada <[email protected]> wrote:
>
>> +1 to rely on expanding {{site.release_latest}}.
>>
>> On Tue, Dec 10, 2019 at 12:05 PM Brian Hulette <[email protected]>
>> wrote:
>>
>>> I was thinking about this recently as well. I requested we add a link to
>>> the java API docs in a website change [1]. I searched around a bit to look
>>> for precedent on how to do this, but I found three different methods:
>>> - Links to a specific version (e.g.
>>> https://beam.apache.org/releases/javadoc/2.0.0/...)
>>> - Links to "current" (e.g.
>>> https://beam.apache.org/releases/javadoc/current/...)
>>> - Links that rely on expanding site.relase_latest (i.e.
>>> https://beam.apache.org/releases/javadoc/{{ site.release_latest}}/...)
>>>
>>> The first seems clearly bad if we want to always use the most recent
>>> version, but it does have the benefit that we don't have to worry about the
>>> links breaking after code changes.
>>>
>>> The latter two are effectively the same, but site.release_latest has the
>>> benefit that its parameterized so we _could_ generate documentation for
>>> other versions if we want to. It also seems to be the most prevalent. So I
>>> think that's the way to go. Are there any objections to updating all of our
>>> links to use site.release_latest?
>>>
>>> I think the only possible concern is we might break a link if we
>>> move/rename a class. It would be nice if there were some way to validate
>>> them.
>>>
>>> Brian
>>>
>>> [1] https://github.com/apache/beam/pull/10273#discussion_r354533080
>>>
>>>
>>> On Fri, Dec 6, 2019 at 7:20 AM Maximilian Michels <[email protected]>
>>> wrote:
>>>
>>>> @Kenn This is not only about breaking changes. We can also add new
>>>> features or settings which will then be advertised in the documentation
>>>> but not be available in older versions.
>>>>
>>>> Having a single source of truth is easier to maintain and better
>>>> discoverable via search engines. However, it forces us to use wordings
>>>> like "Works like this in Beam version <= X.Y, otherwise use..". The
>>>> pragmatic approach there is to just ignore old Beam versions. That's
>>>> not
>>>> super user friendly, but it works.
>>>>
>>>> IMHO the amount of version-specific content in the Beam documentation
>>>> probably does not yet justify forking the documentation for every
>>>> release.
>>>>
>>>> Cheers,
>>>> Max
>>>>
>>>> On 06.12.19 08:13, Alex Van Boxel wrote:
>>>> > It seems also be too complex for the Google Crawler as well. A lot of
>>>> > times I arrived on documentation on an older version of a product
>>>> when I
>>>> > search (aka Google) for something.
>>>> >
>>>> > _/
>>>> > _/ Alex Van Boxel
>>>> >
>>>> >
>>>> > On Fri, Dec 6, 2019 at 6:20 AM Kenneth Knowles <[email protected]
>>>> > <mailto:[email protected]>> wrote:
>>>> >
>>>> > Since we are not making breaking changes (we hope) and we try to
>>>> be
>>>> > careful about performance regressions, I think it is OK to simply
>>>> > encourage users to upgrade to the latest if they expect the
>>>> > narrative documentation to match their version. The versioned API
>>>> > docs are probably enough. We might consider putting more info into
>>>> > the javadocs / pydocs to bridge the gap, if you have seen any
>>>> issues
>>>> > with users hitting trouble.
>>>> >
>>>> > I am saying this for two reasons:
>>>> >
>>>> > - versioning the site is more work, and someone would need to do
>>>> > that work
>>>> > - but more than that, versioned site is more complex for users
>>>> >
>>>> > Kenn
>>>> >
>>>> > On Wed, Dec 4, 2019 at 1:48 PM Ankur Goenka <[email protected]
>>>> > <mailto:[email protected]>> wrote:
>>>> >
>>>> > I agree, having a single website showcase the latest beam
>>>> > versions and encourages users to use the latest Beam version
>>>> > which is very useful.
>>>> > Calling out version limitations are definitely makes users
>>>> life
>>>> > easier.
>>>> >
>>>> > The usecase I have in mind is more on the lines of best
>>>> > practices and recommended way of doing things.
>>>> > One such example is the way we recommend new users to try
>>>> > Portable Flink. We are overhauling and simplifying the user
>>>> > onboarding experience. Though the old way of doing things are
>>>> > still supported, the easier new recommendation for onboarding
>>>> > will only apply from Beam 2.18.
>>>> > We can ofcource create sections on documentation for this
>>>> > usecase but it seems like a poor man's way of versioning :)
>>>> >
>>>> > You also highlighted a great usecase about LTS release. Should
>>>> > we simply separate out the documentations for LTS release and
>>>> > current version to make it easy for the users to navigate the
>>>> > website and reduce management overhead of updating specific
>>>> > sections.
>>>> >
>>>> > A few areas which might benefit from having multiple versions
>>>> > are compatibility matrix, Common pipeline patterns, transform
>>>> > catalog and runner pages.
>>>> >
>>>> >
>>>> > On Wed, Dec 4, 2019 at 6:19 AM Jeff Klukas <
>>>> [email protected]
>>>> > <mailto:[email protected]>> wrote:
>>>> >
>>>> > The API reference docs (Java and Python at least) are
>>>> > versioned, so we have a durable reference there and it's
>>>> > possible to link to particular sections of API docs for
>>>> > particular versions.
>>>> >
>>>> > For the major bits of introductory documentation (like the
>>>> > Beam Programming Guide), I think it's a good thing to have
>>>> > only a single version, so that people referencing it are
>>>> > always getting the most up-to-date wording and
>>>> explanations,
>>>> > although it may be worth adding callouts there about
>>>> minimum
>>>> > versions anywhere we discuss newer features. We should be
>>>> > encouraging the community to stay reasonably current, so I
>>>> > think any feature that's present in the latest LTS release
>>>> > should be fine to assume is available to users, although
>>>> > perhaps we should also state that explicitly on the
>>>> website.
>>>> >
>>>> > Are there particular parts of the Beam website that you
>>>> have
>>>> > in mind that would benefit from versioning? Are there
>>>> > specific cases you see where the current website would be
>>>> > confusing for someone using a Beam SDK that's a few
>>>> versions
>>>> > old?
>>>> >
>>>> > On Tue, Dec 3, 2019 at 6:46 PM Ankur Goenka
>>>> > <[email protected] <mailto:[email protected]>> wrote:
>>>> >
>>>> > Hi,
>>>> >
>>>> > We are constantly adding features to Beam which makes
>>>> > each new Beam version more feature rich and
>>>> compelling.
>>>> > This also means that the old Beam released don't have
>>>> > the new features and might have different ways to do
>>>> > certain things.
>>>> >
>>>> > (I might be wrong here) - Our Beam website only
>>>> publish
>>>> > a single version which is the latest version of
>>>> > documentation.
>>>> > This means that the users working with older SDK don't
>>>> > really have an easy way to lookup documentation for
>>>> old
>>>> > versions of Beam.
>>>> >
>>>> > Proposal: Shall we consider publishing versioned Beam
>>>> > website to help users with old Beam version find the
>>>> > relevant information?
>>>> >
>>>> > Thanks,
>>>> > Ankur
>>>> >
>>>>
>>>
