+1 for using {{site.release_latest}}, which is make more sense to me. Best, Jincheng
Kenneth Knowles <k...@apache.org> 于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 <pabl...@google.com> wrote: > >> +1 to rely on expanding {{site.release_latest}}. >> >> On Tue, Dec 10, 2019 at 12:05 PM Brian Hulette <bhule...@google.com> >> 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 <m...@apache.org> >>> 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 <k...@apache.org >>>> > <mailto:k...@apache.org>> 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 <goe...@google.com >>>> > <mailto:goe...@google.com>> 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 < >>>> jklu...@mozilla.com >>>> > <mailto:jklu...@mozilla.com>> 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 >>>> > <goe...@google.com <mailto:goe...@google.com>> 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 >>>> > >>>> >>>