[DISCUSS] Iceberg Website Contribution Strategy

[Jack Ye <ye...@gmail.com>]

Hi everyone,

As we recently released the new Iceberg website, there are some confusions
and different opinions related to the new way to contribute to the website.

*Current state*
The current website in iceberg-docs repository has 2 parts:
1, the versioned website contents are in the folder "docs", displaying
contents under /docs/<VERSION NUM> path in the website
2. the shared website contents are in the folder "landing-page", displaying
contents under the root / path in the website

Markdown contents are stored under the /content/docs/ subfolder under each
folder in iceberg-docs repo.

The iceberg repository has a folder "docs" with 2 subfolders:
1. "versioned" folder contains files in iceberg-docs repo /docs/content/docs
2. "common" folder contains files in iceberg-docs repo
/landing-page/content/docs

The doc in the iceberg repo is the single source of truth. Contributors
should always contribute to the iceberg repo. Then during each release, the
release manager copies the contents over to the iceberg-docs repo to update
the website. The landing page always displays contents in the main branch.
A new version branch is created to show the versioned docs.

Users are not supposed to make direct changes in iceberg-docs repository,
unless:
1. the user would like to change website layout such as HTML or CSS
2. the user would like to patch a historical versioned doc (a PR should be
submitted against the specific version doc branch but not the main branch
in this case)

The biggest problem of the current process is that the website update
process is manual and binded to release. Small changes to other shared
pages cannot be reflected immediately. Because of this, people start to
make changes in both repositories to sync docs and have changes deployed
faster.

Here we would like to discuss the best way forward with the community. We
have thought about 3 potential approaches so far.

*Approach 1: add auto-sync trigger*
We can add a trigger in the Iceberg repo that runs when docs are updated
(or run it once a day if we don't want to sync too frequently) to sync
changes in Iceberg repo to iceberg-docs repo.

This also means there is less work for the release manager when managing a
release, because docs are already synced and there is no need for manual
copy. The release notes are also posted in the Iceberg repo and synced over.

This requires the trigger to perform a commit to the iceberg-docs
repository. We have some confirmation from the ASF Infra team that this
should be achievable, but we won't know if this could work until we
actually try that.


*Approach 2: remove the common folder in iceberg repo*
We know that for versioned docs we need to release during the new version
release process instead of showing unreleased features to users. However,
shared contents (in the landing page) do not need to wait until the next
release. We can remove /docs/common folder in Iceberg repo, and define that
any change in the common page must be done in iceberg-docs.

This will support immediate reflection of changes in the website for any
edits to the shared content. The contribution guideline is still relatively
clear, although contributors need to know the existence of the iceberg-docs
repo to update contents like blogs, spec, etc.

*Approach 3: keep some shared files in Iceberg repo*
One issue in approach 2 is that spec.md is shared content, but lots of
important design discussions are based on this file. We still want to keep
it in the iceberg repo for developers to reference and update easily. The
new file view-spec.md that will be added for view support should also be
treated similar to spec.md.

To achieve this, we can make an exception to approach 2 to have the common
folder contain important shared docs instead of removing the entire folder.
These docs are only copied to iceberg-docs during each release by the
release manager. But other shared docs can be edited and updated
immediately through iceberg-docs repo PRs.

This approach solves the issue of important shared files in approach 2, but
it also makes doc contribution guidelines more complex. But considering the
fact that pages like release-notes, community, how-to-release are most of
the time only edited by the release manager or a few people closely
involved in the community, this might be a good tradeoff.

It would be really appreciated if people can provide some thoughts about
the preferred approach, any approach that we have not thought about, or any
additional pros and cons of existing approaches.

Best,
Jack Ye