You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by GitBox <gi...@apache.org> on 2022/02/05 00:21:41 UTC
[GitHub] [iceberg-docs] samredai commented on a change in pull request #35: Add contribution guidelines
samredai commented on a change in pull request #35:
URL: https://github.com/apache/iceberg-docs/pull/35#discussion_r799901630
##########
File path: README.md
##########
@@ -26,15 +26,62 @@ 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).
Review comment:
s/to documentation and website/to the documentation website
##########
File path: README.md
##########
@@ -26,15 +26,62 @@ 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.
Review comment:
The landing-page site includes the common markdown files as well (releases, spec, community, etc). We should keep those in `apache/iceberg` too and have PRs opened there, right? That would be simpler--all docs PRs are opened in `apache/iceberg` unless you're hotfixing a previous version in which case you open the PR against that particular version's branch in `apache/iceberg-docs`.
##########
File path: README.md
##########
@@ -26,15 +26,62 @@ 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.
Review comment:
s/cut/cuts
##########
File path: README.md
##########
@@ -26,15 +26,62 @@ 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.
Review comment:
nit: same comment about the clone already being included in the code block.
##########
File path: README.md
##########
@@ -26,15 +26,62 @@ 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.
Review comment:
nit: the code block includes the clone so maybe just say "To start the landing page site locally, run the following."
##########
File path: 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:
Review comment:
Yep, exactly right. In `apache/iceberg` we would have two directories that are intuitively named like `documentation/common` and `documentation/versioned` and they would hold the contents in [docs/content/docs](https://github.com/apache/iceberg-docs/tree/main/docs/content/docs) and [landing-page/content/common](https://github.com/apache/iceberg-docs/tree/main/landing-page/content/common), respectively. The release manager would then just do a full hard-copy over of those two directories (might be worth mentioning that it should be a full copy, meaning deleted files are removed in the destinations as well).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org