This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-site.git
The following commit(s) were added to refs/heads/main by this push:
new 8f870fc19a7 GH-327: [Website] Add note about the need to set GitHub
Pages deployment source branch to `gh-pages` when previewing website changes on
a fork of `apache/arrow-site` (#328)
8f870fc19a7 is described below
commit 8f870fc19a7f3cd40b52f3ae393b4b93a93bfa45
Author: Kevin Gurney <[email protected]>
AuthorDate: Thu Mar 2 15:42:04 2023 -0500
GH-327: [Website] Add note about the need to set GitHub Pages deployment
source branch to `gh-pages` when previewing website changes on a fork of
`apache/arrow-site` (#328)
# Overview
This pull request adds an explicit note to the [Deployment section of
the
README.md](https://github.com/apache/arrow-site/blob/main/README.md#deployment)
about the need to [set the GitHub Pages deployment source
branch](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch)
to `gh-pages` when previewing website changes on a fork of
`apache/arrow-site`.
It isn't immediately obvious that this is a required step. As far as I
can tell, the default deployment source branch will normally be set to
`asf-site` for a fork, which means that any changes to the website won't
deploy on a successful run. This could potentially be quite confusing.
# Qualification
N/A
# Future Directions
N/A
# Notes
N/A
Closes apache/arrow-site#327
---
README.md | 30 ++++++++++++++++++++++++++----
1 file changed, 26 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index 8a76014e32c..80703474c60 100644
--- a/README.md
+++ b/README.md
@@ -65,11 +65,33 @@ bundle exec rake
## Deployment
-On commits to the `main` branch of `apache/arrow-site`, the rendered
+### apache/arrow-site
+
+On a commit to the `main` branch of `apache/arrow-site`, the rendered
static site will be published to the `asf-site` branch using GitHub
-Actions. On a fork, it will deploy to your `gh-pages` branch for
-deployment via GitHub Pages; this is useful for previewing changes
-you're proposing.
+Actions.
+
+### Forks
+
+When implementing changes to the website on a fork, the GitHub Actions
+workflow behaves differently.
+
+On a commit to the `main` branch, the rendered static site will be
+published to a branch named `gh-pages` (rather than `asf-site`). If it doesn't
+already exist, a `gh-pages` branch will be automatically created by the
+GitHub Actions workflow when it succeeds.
+
+The **gh**-**p**ages branch is intended to be used with **G**it**H**ub
**P**ages.
+Deploying changes on the `gh-pages` branch to GitHub Pages is a useful way to
+preview changes to the website. It can also be a helpful way to share changes
+that are still in progress with others, since they can easily view them
+by navigating to the GitHub Pages URL in their web browser.
+
+For the changes on the `gh-pages` branch to be deployed to GitHub Pages,
+the *Source* branch for GitHub Pages deployment must be set to `gh-pages`
+in the repository Settings of your fork (by default, the Source branch
+should be set to `asf-site`). Instructions on how to configure
+the Source branch can be found in the [GitHub Pages
documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch).
FYI: We can also generate the site for https://arrow.apache.org/
to `_site/` locally by the following command line:
