You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@druid.apache.org by Jonathan Wei <jo...@apache.org> on 2020/01/15 03:14:06 UTC
Publish staging docs for release earlier?
Hi all,
We currently publish a staging version of the Druid docs for an upcoming
release at druid.staged.apache.org when we make a release candidate.
I think it'd be better if we published the staging docs for an upcoming
release as soon as the code freeze is made, and keep it updated as doc
backports are made to the upcoming release branch.
This would allow people doing testing or other evaluation on the release
branch to have more usable documentation (using the source markdown files
is not ideal since links to other parts of the druid docs don't work, and
the navigation assist/style of the actual website isn't there).
I wanted to get the community's thoughts on this proposed change.
Thanks,
Jon
Re: Publish staging docs for release earlier?
Posted by Tijo Thomas <ti...@imply.io>.
+1 Nice option
On Wed, Jan 15, 2020 at 10:43 AM Jad Naous <ja...@imply.io> wrote:
> Great idea!
>
> On Tue, Jan 14, 2020, 7:14 PM Jonathan Wei <jo...@apache.org> wrote:
>
> > Hi all,
> >
> > We currently publish a staging version of the Druid docs for an upcoming
> > release at druid.staged.apache.org when we make a release candidate.
> >
> > I think it'd be better if we published the staging docs for an upcoming
> > release as soon as the code freeze is made, and keep it updated as doc
> > backports are made to the upcoming release branch.
> >
> > This would allow people doing testing or other evaluation on the release
> > branch to have more usable documentation (using the source markdown files
> > is not ideal since links to other parts of the druid docs don't work, and
> > the navigation assist/style of the actual website isn't there).
> >
> > I wanted to get the community's thoughts on this proposed change.
> >
> > Thanks,
> > Jon
> >
>
--
Tijo Thomas
Solutions Architect | => Imply , Bangalore , India
Re: Publish staging docs for release earlier?
Posted by Jad Naous <ja...@imply.io>.
Great idea!
On Tue, Jan 14, 2020, 7:14 PM Jonathan Wei <jo...@apache.org> wrote:
> Hi all,
>
> We currently publish a staging version of the Druid docs for an upcoming
> release at druid.staged.apache.org when we make a release candidate.
>
> I think it'd be better if we published the staging docs for an upcoming
> release as soon as the code freeze is made, and keep it updated as doc
> backports are made to the upcoming release branch.
>
> This would allow people doing testing or other evaluation on the release
> branch to have more usable documentation (using the source markdown files
> is not ideal since links to other parts of the druid docs don't work, and
> the navigation assist/style of the actual website isn't there).
>
> I wanted to get the community's thoughts on this proposed change.
>
> Thanks,
> Jon
>
Re: Publish staging docs for release earlier?
Posted by Jad Naous <ja...@imply.io>.
I really like this idea... The django site is a great example for how they
do this.
On Wed, Jan 22, 2020 at 2:28 PM Jonathan Wei <jo...@apache.org> wrote:
> I'm now thinking we should actually publish the docs for an upcoming
> release to the main site instead of the staging site, it would help avoid
> confusion (e.g.
> https://github.com/apache/druid/issues/9066#issuecomment-577232205)
> without
> requiring the release manager to deal with two sets of doc links in places
> such as the release notes.
>
> For example, when we code freeze 0.18.0, we could publish the 0.18.0 docs
> right away to https://druid.apache.org/docs/0.18.0/, but leave the
> "latest"
> directory still pointing to the 0.17.0 docs (or whatever version is the
> latest release at the time).
>
> With that approach, maybe some sort of indicator on the preview 0.18.0 docs
> stating that the docs are for an upcoming unreleased version would be nice.
>
> On Sun, Jan 19, 2020 at 4:36 PM Jad Naous <ja...@imply.io> wrote:
>
> > What I've seen happen in other OSS projects is that the URL is versioned.
> > Master is usually under /dev and releases are under /x.y. /latest points
> to
> > the latest release docs
> >
> > On Sun, Jan 19, 2020, 1:01 PM Jonathan Wei <jo...@apache.org> wrote:
> >
> > > Thanks for the feedback everyone!
> > >
> > > > Even better if we can publish the docs from master somewhere (in
> > addition
> > > to the current release branch). Both are useful to see.
> > >
> > > That sounds useful too, maybe it can live under a `master` directory
> > > alongside `latest` and the specific version docs.
> > >
> > > On Wed, Jan 15, 2020 at 9:27 PM Furkan KAMACI <fu...@gmail.com>
> > > wrote:
> > >
> > > > Hi,
> > > >
> > > > +1!
> > > >
> > > > Kind Regards,
> > > > Furkan KAMACI
> > > >
> > > > 16 Oca 2020 Per, saat 01:56 tarihinde Gian Merlino <gi...@apache.org>
> > > şunu
> > > > yazdı:
> > > >
> > > > > I love the idea.
> > > > >
> > > > > Even better if we can publish the docs from master somewhere (in
> > > addition
> > > > > to the current release branch). Both are useful to see.
> > > > >
> > > > > On Tue, Jan 14, 2020 at 7:14 PM Jonathan Wei <jo...@apache.org>
> > > wrote:
> > > > >
> > > > > > Hi all,
> > > > > >
> > > > > > We currently publish a staging version of the Druid docs for an
> > > > upcoming
> > > > > > release at druid.staged.apache.org when we make a release
> > candidate.
> > > > > >
> > > > > > I think it'd be better if we published the staging docs for an
> > > upcoming
> > > > > > release as soon as the code freeze is made, and keep it updated
> as
> > > doc
> > > > > > backports are made to the upcoming release branch.
> > > > > >
> > > > > > This would allow people doing testing or other evaluation on the
> > > > release
> > > > > > branch to have more usable documentation (using the source
> markdown
> > > > files
> > > > > > is not ideal since links to other parts of the druid docs don't
> > work,
> > > > and
> > > > > > the navigation assist/style of the actual website isn't there).
> > > > > >
> > > > > > I wanted to get the community's thoughts on this proposed change.
> > > > > >
> > > > > > Thanks,
> > > > > > Jon
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Publish staging docs for release earlier?
Posted by Jonathan Wei <jo...@apache.org>.
I'm now thinking we should actually publish the docs for an upcoming
release to the main site instead of the staging site, it would help avoid
confusion (e.g.
https://github.com/apache/druid/issues/9066#issuecomment-577232205) without
requiring the release manager to deal with two sets of doc links in places
such as the release notes.
For example, when we code freeze 0.18.0, we could publish the 0.18.0 docs
right away to https://druid.apache.org/docs/0.18.0/, but leave the "latest"
directory still pointing to the 0.17.0 docs (or whatever version is the
latest release at the time).
With that approach, maybe some sort of indicator on the preview 0.18.0 docs
stating that the docs are for an upcoming unreleased version would be nice.
On Sun, Jan 19, 2020 at 4:36 PM Jad Naous <ja...@imply.io> wrote:
> What I've seen happen in other OSS projects is that the URL is versioned.
> Master is usually under /dev and releases are under /x.y. /latest points to
> the latest release docs
>
> On Sun, Jan 19, 2020, 1:01 PM Jonathan Wei <jo...@apache.org> wrote:
>
> > Thanks for the feedback everyone!
> >
> > > Even better if we can publish the docs from master somewhere (in
> addition
> > to the current release branch). Both are useful to see.
> >
> > That sounds useful too, maybe it can live under a `master` directory
> > alongside `latest` and the specific version docs.
> >
> > On Wed, Jan 15, 2020 at 9:27 PM Furkan KAMACI <fu...@gmail.com>
> > wrote:
> >
> > > Hi,
> > >
> > > +1!
> > >
> > > Kind Regards,
> > > Furkan KAMACI
> > >
> > > 16 Oca 2020 Per, saat 01:56 tarihinde Gian Merlino <gi...@apache.org>
> > şunu
> > > yazdı:
> > >
> > > > I love the idea.
> > > >
> > > > Even better if we can publish the docs from master somewhere (in
> > addition
> > > > to the current release branch). Both are useful to see.
> > > >
> > > > On Tue, Jan 14, 2020 at 7:14 PM Jonathan Wei <jo...@apache.org>
> > wrote:
> > > >
> > > > > Hi all,
> > > > >
> > > > > We currently publish a staging version of the Druid docs for an
> > > upcoming
> > > > > release at druid.staged.apache.org when we make a release
> candidate.
> > > > >
> > > > > I think it'd be better if we published the staging docs for an
> > upcoming
> > > > > release as soon as the code freeze is made, and keep it updated as
> > doc
> > > > > backports are made to the upcoming release branch.
> > > > >
> > > > > This would allow people doing testing or other evaluation on the
> > > release
> > > > > branch to have more usable documentation (using the source markdown
> > > files
> > > > > is not ideal since links to other parts of the druid docs don't
> work,
> > > and
> > > > > the navigation assist/style of the actual website isn't there).
> > > > >
> > > > > I wanted to get the community's thoughts on this proposed change.
> > > > >
> > > > > Thanks,
> > > > > Jon
> > > > >
> > > >
> > >
> >
>
Re: Publish staging docs for release earlier?
Posted by Jad Naous <ja...@imply.io>.
What I've seen happen in other OSS projects is that the URL is versioned.
Master is usually under /dev and releases are under /x.y. /latest points to
the latest release docs
On Sun, Jan 19, 2020, 1:01 PM Jonathan Wei <jo...@apache.org> wrote:
> Thanks for the feedback everyone!
>
> > Even better if we can publish the docs from master somewhere (in addition
> to the current release branch). Both are useful to see.
>
> That sounds useful too, maybe it can live under a `master` directory
> alongside `latest` and the specific version docs.
>
> On Wed, Jan 15, 2020 at 9:27 PM Furkan KAMACI <fu...@gmail.com>
> wrote:
>
> > Hi,
> >
> > +1!
> >
> > Kind Regards,
> > Furkan KAMACI
> >
> > 16 Oca 2020 Per, saat 01:56 tarihinde Gian Merlino <gi...@apache.org>
> şunu
> > yazdı:
> >
> > > I love the idea.
> > >
> > > Even better if we can publish the docs from master somewhere (in
> addition
> > > to the current release branch). Both are useful to see.
> > >
> > > On Tue, Jan 14, 2020 at 7:14 PM Jonathan Wei <jo...@apache.org>
> wrote:
> > >
> > > > Hi all,
> > > >
> > > > We currently publish a staging version of the Druid docs for an
> > upcoming
> > > > release at druid.staged.apache.org when we make a release candidate.
> > > >
> > > > I think it'd be better if we published the staging docs for an
> upcoming
> > > > release as soon as the code freeze is made, and keep it updated as
> doc
> > > > backports are made to the upcoming release branch.
> > > >
> > > > This would allow people doing testing or other evaluation on the
> > release
> > > > branch to have more usable documentation (using the source markdown
> > files
> > > > is not ideal since links to other parts of the druid docs don't work,
> > and
> > > > the navigation assist/style of the actual website isn't there).
> > > >
> > > > I wanted to get the community's thoughts on this proposed change.
> > > >
> > > > Thanks,
> > > > Jon
> > > >
> > >
> >
>
Re: Publish staging docs for release earlier?
Posted by Jonathan Wei <jo...@apache.org>.
Thanks for the feedback everyone!
> Even better if we can publish the docs from master somewhere (in addition
to the current release branch). Both are useful to see.
That sounds useful too, maybe it can live under a `master` directory
alongside `latest` and the specific version docs.
On Wed, Jan 15, 2020 at 9:27 PM Furkan KAMACI <fu...@gmail.com>
wrote:
> Hi,
>
> +1!
>
> Kind Regards,
> Furkan KAMACI
>
> 16 Oca 2020 Per, saat 01:56 tarihinde Gian Merlino <gi...@apache.org> şunu
> yazdı:
>
> > I love the idea.
> >
> > Even better if we can publish the docs from master somewhere (in addition
> > to the current release branch). Both are useful to see.
> >
> > On Tue, Jan 14, 2020 at 7:14 PM Jonathan Wei <jo...@apache.org> wrote:
> >
> > > Hi all,
> > >
> > > We currently publish a staging version of the Druid docs for an
> upcoming
> > > release at druid.staged.apache.org when we make a release candidate.
> > >
> > > I think it'd be better if we published the staging docs for an upcoming
> > > release as soon as the code freeze is made, and keep it updated as doc
> > > backports are made to the upcoming release branch.
> > >
> > > This would allow people doing testing or other evaluation on the
> release
> > > branch to have more usable documentation (using the source markdown
> files
> > > is not ideal since links to other parts of the druid docs don't work,
> and
> > > the navigation assist/style of the actual website isn't there).
> > >
> > > I wanted to get the community's thoughts on this proposed change.
> > >
> > > Thanks,
> > > Jon
> > >
> >
>
Re: Publish staging docs for release earlier?
Posted by Furkan KAMACI <fu...@gmail.com>.
Hi,
+1!
Kind Regards,
Furkan KAMACI
16 Oca 2020 Per, saat 01:56 tarihinde Gian Merlino <gi...@apache.org> şunu
yazdı:
> I love the idea.
>
> Even better if we can publish the docs from master somewhere (in addition
> to the current release branch). Both are useful to see.
>
> On Tue, Jan 14, 2020 at 7:14 PM Jonathan Wei <jo...@apache.org> wrote:
>
> > Hi all,
> >
> > We currently publish a staging version of the Druid docs for an upcoming
> > release at druid.staged.apache.org when we make a release candidate.
> >
> > I think it'd be better if we published the staging docs for an upcoming
> > release as soon as the code freeze is made, and keep it updated as doc
> > backports are made to the upcoming release branch.
> >
> > This would allow people doing testing or other evaluation on the release
> > branch to have more usable documentation (using the source markdown files
> > is not ideal since links to other parts of the druid docs don't work, and
> > the navigation assist/style of the actual website isn't there).
> >
> > I wanted to get the community's thoughts on this proposed change.
> >
> > Thanks,
> > Jon
> >
>
Re: Publish staging docs for release earlier?
Posted by Gian Merlino <gi...@apache.org>.
I love the idea.
Even better if we can publish the docs from master somewhere (in addition
to the current release branch). Both are useful to see.
On Tue, Jan 14, 2020 at 7:14 PM Jonathan Wei <jo...@apache.org> wrote:
> Hi all,
>
> We currently publish a staging version of the Druid docs for an upcoming
> release at druid.staged.apache.org when we make a release candidate.
>
> I think it'd be better if we published the staging docs for an upcoming
> release as soon as the code freeze is made, and keep it updated as doc
> backports are made to the upcoming release branch.
>
> This would allow people doing testing or other evaluation on the release
> branch to have more usable documentation (using the source markdown files
> is not ideal since links to other parts of the druid docs don't work, and
> the navigation assist/style of the actual website isn't there).
>
> I wanted to get the community's thoughts on this proposed change.
>
> Thanks,
> Jon
>