From e638f27fc4a641a0e0e3fc5bce6e84210abb4175 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Fri, 4 Feb 2022 15:18:53 -0800 Subject: [PATCH 1/4] Add contribution guidelines --- README.md | 73 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 49 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index eef928b13..274a4344e 100644 --- a/README.md +++ b/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). \ No newline at end of file From 9f3c8e180b73bc369bbade704d3df9312cd26cb5 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Fri, 4 Feb 2022 15:21:30 -0800 Subject: [PATCH 2/4] fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 274a4344e..aea03ed1a 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ cd docs && hugo serve 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 +cp -r iceberg/documentation/* iceberg-docs/docs/content/docs ``` ## Scanning For Broken Links From 36df638a095dc827baab96a04c7967bb38d7bafc Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Fri, 4 Feb 2022 15:26:00 -0800 Subject: [PATCH 3/4] deal with 2 parts of the sites --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index aea03ed1a..85b3ef3ed 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,10 @@ cd docs && hugo serve 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/docs/content/docs +rm -rf docs/content/docs +rm -rf landing-page/content/common +cp -r /documentation/docs docs/content/docs +cp -r /documentation/common docs/content/common ``` ## Scanning For Broken Links From f66716ffbfd969a4cde2d3c692fb9f06522b77a8 Mon Sep 17 00:00:00 2001 From: Jack Ye Date: Fri, 4 Feb 2022 17:15:42 -0800 Subject: [PATCH 4/4] update based on comments --- README.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 85b3ef3ed..a663605e6 100644 --- a/README.md +++ b/README.md @@ -26,45 +26,58 @@ 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. The Javadocs are in the `./javadoc` directory. +documentation sites are completely self-contained in the `./landing-page` and `./docs` directories, respectively. +The Javadocs are in the `./javadoc` directory. + +## Relationship to the Iceberg Repository + +The `documentation` folder in the [Iceberg repository](https://github.com/apache/iceberg) contains all the markdown docs used by the website. +The `common` subfolder contains contents used by the landing page. +The `versioned` subfolder contains the contents different for each version. + +During each new release, the release manager copies contents from the Iceberg repository to this docs repository and cuts a new version branch. +Contents under `common` are copied to `./landing-page/contents/common` here, +and contents under `versioned` are copied to `./docs/contents/docs` here. +Javadocs generated from the release are copied to the `javadoc` directory. # 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 markdown contents should be submitted directly in the Iceberg repository. -Changes to the landing page should be submitted to this repository against the `main` branch. +Changes to the website appearance (e.g. HTML, CSS changes) 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). +All issues related to the doc website should still be submitted to the [Iceberg repository](https://github.com/apache/iceberg). +The GitHub Issues feature of this repository is disabled. ## Running Locally -To start the landing page site locally, clone this repository and run the following. +Clone this repository to run the website locally: ```shell git clone git@github.com:apache/iceberg-docs.git +cd iceberg-docs +``` + +To start the landing page site locally, run: +```shell cd landing-page && hugo serve ``` -To start the documentation site locally, clone this repository and run the following. +To start the documentation site locally, run: ```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 rm -rf docs/content/docs rm -rf landing-page/content/common -cp -r /documentation/docs docs/content/docs +cp -r /documentation/versioned docs/content/docs cp -r /documentation/common docs/content/common ``` @@ -72,7 +85,6 @@ cp -r /documentation/common docs/content/common 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 @@ -92,11 +104,11 @@ yet exist in the `asf-site` branch, it will be created. Additionally, the contents of the `javadoc` directory is deployed to a `javadoc/` directory in the `asf-site` branch. -#### Latest Docs +### Latest Docs In [./docs/redirect/index.html](./docs/redirect/index.html), a redirect meta tag exists to forward `/docs` and `/latest` to `/docs/latest`. -# `asf-site` Branch Structure +## `asf-site` Branch Structure The `asf-site` branch structure is the following: ```