Add contribution guidelines

README.md

@@ -26,15 +26,59 @@ It's built with [Hugo](https://gohugo.io/) and hosted at https://iceberg.apache.
 
 The Iceberg documentation site is actually constructed from two hugo sites. The first, is the landing page. The second site, 
 is the documentation site which contains the full Iceberg documentation, including the javadoc. The landing page and
-documentation sites are completely self-contained in the `./landing-page` and `./docs` directories, respectively.
+documentation sites are completely self-contained in the `./landing-page` and `./docs` directories, respectively. The Javadocs are in the `./javadoc` directory.
 
-# Landing Page Deployment
+# How to Contribute
+
+## Submitting Pull Requests
+
+All pull requests to update the latest documentations should be submitted to the [Iceberg repository](https://github.com/apache/iceberg).
+When Iceberg publishes a new release, the release manager copies all the documentation to this repository and cut a new version branch.
+
+Changes to the landing page should be submitted to this repository against the `main` branch.
+
+Changes to the documentation of old Iceberg versions should be submitted to this repository against the specific version branch.
+
+## Reporting Issues
+
+All issues related to documentation and website should still be submitted to the [Iceberg repository](https://github.com/apache/iceberg).
+
+## Running Locally
+
+To start the landing page site locally, clone this repository and run the following.
+```shell
+git clone git@github.com:apache/iceberg-docs.git
+cd landing-page && hugo serve
+```
+
+To start the documentation site locally, clone this repository and run the following.
+```shell
+git clone git@github.com:apache/iceberg-docs.git
+git submodule update --init
+cd docs && hugo serve
+```
+
+## Viewing Latest Website
+
+If you would like to see how the latest website looks based on the documentation in the Iceberg repository, you can copy docs to this repository by:
+```shell
+cp -r iceberg/documentation/* iceberg-docs/content/docs
+```
+
+## Scanning For Broken Links
+
+If you'd like to scan for broken links, one available tool is linkcheck that can be found [here](https://github.com/filiph/linkcheck).
+
+
+# How the Website is Deployed
+
+## Landing Page Deployment
 
 The landing page site is automatically deployed to the root of the `asf-site` branch by the `deploy-landing-page`
 job in the [deployment workflow](./.github/workflows/deploy.yml). There is only a single version of the landing
 page site, and the `deploy-landing-page` job only runs on commits to the `main` branch.
 
-# Docs Deployment
+## Docs Deployment
 
 The docs site is automatically deployed to the `docs` directory in the asf-site branch, into a sub-directory
 named after the branch where the commit occured. This is performed by the `deploy-docs` job in the
@@ -75,29 +119,10 @@ in the `asf-site` branch's `javadoc` directory.
 A `main` branch commit deploys the landing page site **only** and overwrites the landing page site at
 the root of the `asf-site` branch.
 
-# Redirects
+## Redirects
 
 Redirects within one of the two sites can easily be done using the `aliases` keyword in the YAML Front Matter.
 You can read more about this Hugo URL Management feature [here](https://gohugo.io/content-management/urls/#yaml-front-matter).
 
 For root level redirects that are outside of both sites, the `./redirects` directory contains pages with redirect `meta` tags.
-These are all deployed at the root level of the `asf-site` branch by the `Deploy redirects` step in the [deployment workflow](./.github/workflows/deploy.yml).
-
-# Running Locally
-
-To start the landing page site locally, clone this repository and run the following.
-```
-git clone git@github.com:apache/iceberg-docs.git
-cd landing-page && hugo serve
-```
-
-To start the documentation site locally, clone this repository and run the following.
-```
-git clone git@github.com:apache/iceberg-docs.git
-git submodule update --init
-cd docs && hugo serve
-```
-
-# Scanning For Broken Links
-
-If you'd like to scan for broken links, one available tool is linkcheck that can be found [here](https://github.com/filiph/linkcheck).
+These are all deployed at the root level of the `asf-site` branch by the `Deploy redirects` step in the [deployment workflow](./.github/workflows/deploy.yml).