Remove "--for-production" flag from docs building #32564
Conversation
We had two types of documentation building: * latest * for production But in fact they never overlapped and we were never mixing the two We used the latest for all development work and for production for releasing to "airflow.apache.org". However as we saw in apache#32562 (triggered by apache#32495 changing the build in main to run with `--for-production` flag - we actually do not need the "latest" builds at all. Everything can be build with "for production" by default. This change removes the `--for-production` flag entirely, leaving the "for production" build mode as the only one available.
potiuk
requested review from
ashb,
jedcunningham,
kaxil and
pierrejeambrun
as code owners
potiuk
requested review from
amoghrajesh,
eladkal,
ephraimbuddy and
utkarsharma2
| """Build documentation in the container.""" | ||
| if for_production and not clean_build: | ||
| get_console().print("\n[warning]When building docs for production, clean-build is forced\n") | ||
| clean_build = True |
There was a problem hiding this comment.
Just double checking, for_production is now by default, before we were forcing clean-build when for_production was True. Does it make sense to keep that option then? Now we can have clean_build = False although for_production is like True
There was a problem hiding this comment.
Yes. That's good point and keen eye :) . I've thought about it to but we are pretty well covered here.
The --clean-build flag makes rebuilding docs slow (because it deletes all the cache) - so we certainly do not want to have it enabled by default. And the "force clean build for production" was added there mostly as a protection against somoene mistakenly building docs without --clean-build while releasing it and possibly publishing some old documentation.
However since it was introduced, we've also been very keen on perfecting our release process and we largely simply copy&paste the steps from here:
- https://github.com/apache/airflow/blob/main/dev/README_RELEASE_AIRFLOW.md#publish-documentation
- https://github.com/apache/airflow/blob/main/dev/README_RELEASE_HELM_CHART.md#publish-documentation
- https://github.com/apache/airflow/blob/main/dev/README_RELEASE_PROVIDER_PACKAGES.md#prepare-documentation
As you can check (and I double checked it before submitting this PR) in all cases there we have --clean-build added as a flag. Yes. it is not perfect, someone impatient might want to skip the copy&paste step but we really focus in our release management team on following the release process "by-the-book" and I think we are all aware that we should not do shortcuts. Also the risk is small, even if build is not clean, the probability of breaking docs is very small - and in most cases the problem will be that the build will fail, because some links will be missing in old docs etc.
So I think we are well covered.
There was a problem hiding this comment.
Makes sense, thanks for the details
ephraimbuddy
added
the
changelog:skip
4 participants
We had two types of documentation building:
But in fact they never overlapped and we were never mixing the two We used the latest for all development work and for production for releasing to "airflow.apache.org".
However as we saw in #32562 (triggered by #32495 changing the build in main to run with
--for-productionflag - we actually do not need the "latest" builds at all. Everything can be build with "for production" by default.This change removes the
--for-productionflag entirely, leaving the "for production" build mode as the only one available.^ Add meaningful description above
Read the Pull Request Guidelines for more information.
In case of fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in a newsfragment file, named
{pr_number}.significant.rstor{issue_number}.significant.rst, in newsfragments.