[REMINDER] Build docs before merging

[Till Rohrmann]

Hi everyone,

I noticed in the last couple of days that our docs were broken. The main
reason was invalid links using the {% link %} tag. The best way to avoid
this situation is to build the docs before merging them [1]. That way, we
can ensure that they are not broken.

[1] https://github.com/apache/flink/tree/master/docs#build

Cheers,
Till

[Jark Wu-2]

+1 for this. Would be better to run the `check_links.sh` for broken links.
Btw, could we add the docs build and check into PR CI.
I think it would be better to guarantee this in the process.

Best,
Jark

On Wed, 18 Nov 2020 at 18:08, Till Rohrmann <[hidden email]> wrote:

> Hi everyone,
>
> I noticed in the last couple of days that our docs were broken. The main
> reason was invalid links using the {% link %} tag. The best way to avoid
> this situation is to build the docs before merging them [1]. That way, we
> can ensure that they are not broken.
>
> [1] https://github.com/apache/flink/tree/master/docs#build
>
> Cheers,
> Till
>

[Till Rohrmann]

I think automating the check is a good idea since everything which is not
automated will be forgotten at some point.

Cheers,
Till

On Wed, Nov 18, 2020 at 12:56 PM Jark Wu <[hidden email]> wrote:

> +1 for this. Would be better to run the `check_links.sh` for broken links.
> Btw, could we add the docs build and check into PR CI.
> I think it would be better to guarantee this in the process.
>
> Best,
> Jark
>
> On Wed, 18 Nov 2020 at 18:08, Till Rohrmann <[hidden email]> wrote:
>
> > Hi everyone,
> >
> > I noticed in the last couple of days that our docs were broken. The main
> > reason was invalid links using the {% link %} tag. The best way to avoid
> > this situation is to build the docs before merging them [1]. That way, we
> > can ensure that they are not broken.
> >
> > [1] https://github.com/apache/flink/tree/master/docs#build
> >
> > Cheers,
> > Till
> >
>

[Robert Metzger]

Actually, the check_links.sh script is called in the nightly CI runs

https://github.com/apache/flink/blob/master/tools/azure-pipelines/build-apache-repo.yml#L145
-->  https://github.com/apache/flink/blob/master/tools/ci/docs.sh#L30+

It was just broken for a while, but fixed by Dian 2 weeks ago.


On Wed, Nov 18, 2020 at 6:09 PM Till Rohrmann <[hidden email]> wrote:

> I think automating the check is a good idea since everything which is not
> automated will be forgotten at some point.
>
> Cheers,
> Till
>
> On Wed, Nov 18, 2020 at 12:56 PM Jark Wu <[hidden email]> wrote:
>
> > +1 for this. Would be better to run the `check_links.sh` for broken
> links.
> > Btw, could we add the docs build and check into PR CI.
> > I think it would be better to guarantee this in the process.
> >
> > Best,
> > Jark
> >
> > On Wed, 18 Nov 2020 at 18:08, Till Rohrmann <[hidden email]>
> wrote:
> >
> > > Hi everyone,
> > >
> > > I noticed in the last couple of days that our docs were broken. The
> main
> > > reason was invalid links using the {% link %} tag. The best way to
> avoid
> > > this situation is to build the docs before merging them [1]. That way,
> we
> > > can ensure that they are not broken.
> > >
> > > [1] https://github.com/apache/flink/tree/master/docs#build
> > >
> > > Cheers,
> > > Till
> > >
> >
>

[Jark Wu-2]

Is it possible to move it to PR CI?

I have seen many documentation link issues these days.

Best,
Jark

On Tue, 24 Nov 2020 at 15:56, Robert Metzger <[hidden email]> wrote:

> Actually, the check_links.sh script is called in the nightly CI runs
>
>
> https://github.com/apache/flink/blob/master/tools/azure-pipelines/build-apache-repo.yml#L145
> -->  https://github.com/apache/flink/blob/master/tools/ci/docs.sh#L30+
>
> It was just broken for a while, but fixed by Dian 2 weeks ago.
>
>
> On Wed, Nov 18, 2020 at 6:09 PM Till Rohrmann <[hidden email]>
> wrote:
>
> > I think automating the check is a good idea since everything which is not
> > automated will be forgotten at some point.
> >
> > Cheers,
> > Till
> >
> > On Wed, Nov 18, 2020 at 12:56 PM Jark Wu <[hidden email]> wrote:
> >
> > > +1 for this. Would be better to run the `check_links.sh` for broken
> > links.
> > > Btw, could we add the docs build and check into PR CI.
> > > I think it would be better to guarantee this in the process.
> > >
> > > Best,
> > > Jark
> > >
> > > On Wed, 18 Nov 2020 at 18:08, Till Rohrmann <[hidden email]>
> > wrote:
> > >
> > > > Hi everyone,
> > > >
> > > > I noticed in the last couple of days that our docs were broken. The
> > main
> > > > reason was invalid links using the {% link %} tag. The best way to
> > avoid
> > > > this situation is to build the docs before merging them [1]. That
> way,
> > we
> > > > can ensure that they are not broken.
> > > >
> > > > [1] https://github.com/apache/flink/tree/master/docs#build
> > > >
> > > > Cheers,
> > > > Till
> > > >
> > >
> >
>

[Robert Metzger]

Yes, that should be very easy to do. Just move the docs_404_check to the
"ci" stage in "build-apache-repo.yml". Maybe it makes sense to extend the
build_properties.sh check to test if the change includes any docs changes.
If not, we could skip the check to save some resources.

Do you want to open a PR for this?

On Tue, Nov 24, 2020 at 10:03 AM Jark Wu <[hidden email]> wrote:

> Is it possible to move it to PR CI?
>
> I have seen many documentation link issues these days.
>
> Best,
> Jark
>
> On Tue, 24 Nov 2020 at 15:56, Robert Metzger <[hidden email]> wrote:
>
> > Actually, the check_links.sh script is called in the nightly CI runs
> >
> >
> >
> https://github.com/apache/flink/blob/master/tools/azure-pipelines/build-apache-repo.yml#L145
> > -->  https://github.com/apache/flink/blob/master/tools/ci/docs.sh#L30+
> >
> > It was just broken for a while, but fixed by Dian 2 weeks ago.
> >
> >
> > On Wed, Nov 18, 2020 at 6:09 PM Till Rohrmann <[hidden email]>
> > wrote:
> >
> > > I think automating the check is a good idea since everything which is
> not
> > > automated will be forgotten at some point.
> > >
> > > Cheers,
> > > Till
> > >
> > > On Wed, Nov 18, 2020 at 12:56 PM Jark Wu <[hidden email]> wrote:
> > >
> > > > +1 for this. Would be better to run the `check_links.sh` for broken
> > > links.
> > > > Btw, could we add the docs build and check into PR CI.
> > > > I think it would be better to guarantee this in the process.
> > > >
> > > > Best,
> > > > Jark
> > > >
> > > > On Wed, 18 Nov 2020 at 18:08, Till Rohrmann <[hidden email]>
> > > wrote:
> > > >
> > > > > Hi everyone,
> > > > >
> > > > > I noticed in the last couple of days that our docs were broken. The
> > > main
> > > > > reason was invalid links using the {% link %} tag. The best way to
> > > avoid
> > > > > this situation is to build the docs before merging them [1]. That
> > way,
> > > we
> > > > > can ensure that they are not broken.
> > > > >
> > > > > [1] https://github.com/apache/flink/tree/master/docs#build
> > > > >
> > > > > Cheers,
> > > > > Till
> > > > >
> > > >
> > >
> >
>

[Jark Wu-2]

Yes. I have opened a pull request:
https://github.com/apache/flink/pull/14204

Best,
Jark

On Tue, 24 Nov 2020 at 17:38, Robert Metzger <[hidden email]> wrote:

> Yes, that should be very easy to do. Just move the docs_404_check to the
> "ci" stage in "build-apache-repo.yml". Maybe it makes sense to extend the
> build_properties.sh check to test if the change includes any docs changes.
> If not, we could skip the check to save some resources.
>
> Do you want to open a PR for this?
>
> On Tue, Nov 24, 2020 at 10:03 AM Jark Wu <[hidden email]> wrote:
>
> > Is it possible to move it to PR CI?
> >
> > I have seen many documentation link issues these days.
> >
> > Best,
> > Jark
> >
> > On Tue, 24 Nov 2020 at 15:56, Robert Metzger <[hidden email]>
> wrote:
> >
> > > Actually, the check_links.sh script is called in the nightly CI runs
> > >
> > >
> > >
> >
> https://github.com/apache/flink/blob/master/tools/azure-pipelines/build-apache-repo.yml#L145
> > > -->  https://github.com/apache/flink/blob/master/tools/ci/docs.sh#L30+
> > >
> > > It was just broken for a while, but fixed by Dian 2 weeks ago.
> > >
> > >
> > > On Wed, Nov 18, 2020 at 6:09 PM Till Rohrmann <[hidden email]>
> > > wrote:
> > >
> > > > I think automating the check is a good idea since everything which is
> > not
> > > > automated will be forgotten at some point.
> > > >
> > > > Cheers,
> > > > Till
> > > >
> > > > On Wed, Nov 18, 2020 at 12:56 PM Jark Wu <[hidden email]> wrote:
> > > >
> > > > > +1 for this. Would be better to run the `check_links.sh` for broken
> > > > links.
> > > > > Btw, could we add the docs build and check into PR CI.
> > > > > I think it would be better to guarantee this in the process.
> > > > >
> > > > > Best,
> > > > > Jark
> > > > >
> > > > > On Wed, 18 Nov 2020 at 18:08, Till Rohrmann <[hidden email]>
> > > > wrote:
> > > > >
> > > > > > Hi everyone,
> > > > > >
> > > > > > I noticed in the last couple of days that our docs were broken.
> The
> > > > main
> > > > > > reason was invalid links using the {% link %} tag. The best way
> to
> > > > avoid
> > > > > > this situation is to build the docs before merging them [1]. That
> > > way,
> > > > we
> > > > > > can ensure that they are not broken.
> > > > > >
> > > > > > [1] https://github.com/apache/flink/tree/master/docs#build
> > > > > >
> > > > > > Cheers,
> > > > > > Till
> > > > > >
> > > > >
> > > >
> > >
> >
>