You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-dev@db.apache.org by GitBox <gi...@apache.org> on 2021/01/14 12:40:20 UTC
[GitHub] [db-jdo-site] tobous commented on a change in pull request #14: Update README.md
tobous commented on a change in pull request #14:
URL: https://github.com/apache/db-jdo-site/pull/14#discussion_r557338507
##########
File path: README.md
##########
@@ -7,9 +7,9 @@ The website is mirrored on https://apache.github.io/db-jdo-site/.
## Building the Site
-The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/).
+The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/). For details on publishing the site see below.
-The site can be built by calling `mvn clean compile`. This generates the HTML files in `target/site`.
+The site can be built by calling `mvn clean install`. This generates the HTML files in `target/site`.
Review comment:
Calling the `install` task has the added side-effect of copying the build results into the `docs`folder. This should at least be mentioned here.
```suggestion
The site can be built by calling `mvn clean install`. This generates the HTML files in `target/site` and copies them into the `docs/` directory.
```
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
* Commit the source changes (not the build artifacts) and open a pull request.
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
+
+### PUBLISHING THE SITE
Review comment:
I would suggest using title case for the section headings.
```suggestion
### Publishing the Site
```
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
* Commit the source changes (not the build artifacts) and open a pull request.
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
+
+### PUBLISHING THE SITE
+After changes have been made to the sources in the `db-jdo-site/src/main/asciidoc` or `db-jdo-site/src/main/template` directory, changes will be published automatically to the live web site by simply pushing changes to the master branch of the repository. The process is as follows:
+
+1. Pushing changes to the master branch invokes the post-push script in `db-jdo-site/.github/workflows/deploy-site.yml` which builds the site in `db-jdo-site/target/` via `mvn clean install`.
+
+1. If the build is successful, the files are copied from `db-jdo-site/target/` to `db-jdo-site/docs/`. The `db-jdo-site/docs` directory is checked to see if any changes have been made.
Review comment:
I think markdown fixes these indices for you, but correctly numbering the list entries would still be preferable in my opinion.
Also, the copying described in this step is now done as part of the maven task, so it should probably be mentioned as part of the first step instead.
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
* Commit the source changes (not the build artifacts) and open a pull request.
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
+
+### PUBLISHING THE SITE
+After changes have been made to the sources in the `db-jdo-site/src/main/asciidoc` or `db-jdo-site/src/main/template` directory, changes will be published automatically to the live web site by simply pushing changes to the master branch of the repository. The process is as follows:
+
+1. Pushing changes to the master branch invokes the post-push script in `db-jdo-site/.github/workflows/deploy-site.yml` which builds the site in `db-jdo-site/target/` via `mvn clean install`.
+
+1. If the build is successful, the files are copied from `db-jdo-site/target/` to `db-jdo-site/docs/`. The `db-jdo-site/docs` directory is checked to see if any changes have been made.
+
+1. It is possible that the user made changes to `db-jdo-site/src/main/asciidoc/` and also compiled and pushed them to `db-jdo-site/docs/`). In this case, proceed to step 5.
Review comment:
Markdown also allows for more complex lists. You could add this step and the following steps as sub-entries in the list to make it easier to read. As an example:
1. Stuff
2. More stuff
a. option 1
b. option 2
3. Finally even more stuff
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
Review comment:
With this new call, the build artifacts are automatically copied to the `docs` directory, which is not part of the `.gitignore`. As a result, such changes could (accidentally) be included in the commit if everything in the workspace is added to the staging area (i.e. by using `git add .`, `git add -u`, or ` git commit -a`).
For this reason, I would suggest still keeping `mvn clean compile` in this section or at least mentioning that the build artifacts are copied to `docs` and should be avoided when adding changes to the staging area.
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
* Commit the source changes (not the build artifacts) and open a pull request.
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
+
+### PUBLISHING THE SITE
+After changes have been made to the sources in the `db-jdo-site/src/main/asciidoc` or `db-jdo-site/src/main/template` directory, changes will be published automatically to the live web site by simply pushing changes to the master branch of the repository. The process is as follows:
+
+1. Pushing changes to the master branch invokes the post-push script in `db-jdo-site/.github/workflows/deploy-site.yml` which builds the site in `db-jdo-site/target/` via `mvn clean install`.
Review comment:
How about adding a static link to the workflow file?
```suggestion
1. Pushing changes to the master branch invokes the post-push script in [`db-jdo-site/.github/workflows/deploy-site.yml`](https://github.com/apache/db-jdo-site/blob/master/.github/workflows/deploy-site.yml) which builds the site in `db-jdo-site/target/` via `mvn clean install`.
```
##########
File path: README.md
##########
@@ -7,9 +7,9 @@ The website is mirrored on https://apache.github.io/db-jdo-site/.
## Building the Site
-The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/).
+The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/). For details on publishing the site see below.
Review comment:
Add a relative link to the referenced section?
```suggestion
The content and styling of the site is defined in the [AsciiDoc](https://asciidoc.org/) format. It is built using [Maven](https://maven.apache.org/). For details on publishing the site see section [Publishing the Site](#publishing-the-site).
```
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
* Commit the source changes (not the build artifacts) and open a pull request.
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
+
+### PUBLISHING THE SITE
+After changes have been made to the sources in the `db-jdo-site/src/main/asciidoc` or `db-jdo-site/src/main/template` directory, changes will be published automatically to the live web site by simply pushing changes to the master branch of the repository. The process is as follows:
+
+1. Pushing changes to the master branch invokes the post-push script in `db-jdo-site/.github/workflows/deploy-site.yml` which builds the site in `db-jdo-site/target/` via `mvn clean install`.
+
+1. If the build is successful, the files are copied from `db-jdo-site/target/` to `db-jdo-site/docs/`. The `db-jdo-site/docs` directory is checked to see if any changes have been made.
+
+1. It is possible that the user made changes to `db-jdo-site/src/main/asciidoc/` and also compiled and pushed them to `db-jdo-site/docs/`). In this case, proceed to step 5.
+
+1. If changes were made to the docs directory by the post-push script, the script then commits the changes to the master branch using the same credentials as were used by the original push.
+
+1. Once the changes have been made to `db-jdo-site/docs/` the script in `db-jdo-site/.asf.yaml` is automatically invoked. This script is executed by Apache Infrastructure machines, and it publishes changes to `db.apache.org/jdo`. It may take some time for the changes to be seen on the live site.
Review comment:
How about linking to the wiki entry that explains the `.asf.yaml` configuration. https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features#git.asf.yamlfeatures-WebSiteDeploymentServiceforGitRepositories was the first thing that popped up for me.
Also, I am not sure whether the description is correct (even though it does not matter much in this case). From my understanding, the script is invoked every time the specified branch is pushed, independently of whether the `content`/`docs` directory is modified or not. The result is basically the same for this case as any invocations without changes to the `content`/`docs` directory won't cause any changes to the site.
##########
File path: README.md
##########
@@ -39,8 +39,22 @@ Contributions to this repository follow the default [GitHub workflow](https://gu
To contribute changes, you can follow these steps:
* Adapt the AsciiDoc files in `src/main/asciidoc` or the website menu in `src/main/template`.
- * Call `mvn clean compile` to build the site and verify the generated website by viewing it locally with a web browser.
+ * Call `mvn clean install` to build the site and verify the generated website by viewing `target/index.html` locally with a web browser.
* Commit the source changes (not the build artifacts) and open a pull request.
### TODO
* If you find any issues please provide a PR or [create a JIRA ticket](https://issues.apache.org/jira/projects/JDO/issues/?filter=allopenissues)
+
+### PUBLISHING THE SITE
+After changes have been made to the sources in the `db-jdo-site/src/main/asciidoc` or `db-jdo-site/src/main/template` directory, changes will be published automatically to the live web site by simply pushing changes to the master branch of the repository. The process is as follows:
+
+1. Pushing changes to the master branch invokes the post-push script in `db-jdo-site/.github/workflows/deploy-site.yml` which builds the site in `db-jdo-site/target/` via `mvn clean install`.
+
+1. If the build is successful, the files are copied from `db-jdo-site/target/` to `db-jdo-site/docs/`. The `db-jdo-site/docs` directory is checked to see if any changes have been made.
+
+1. It is possible that the user made changes to `db-jdo-site/src/main/asciidoc/` and also compiled and pushed them to `db-jdo-site/docs/`). In this case, proceed to step 5.
+
+1. If changes were made to the docs directory by the post-push script, the script then commits the changes to the master branch using the same credentials as were used by the original push.
Review comment:
This is not true. The author data of the top commit on the pushed branch is used, which does not necessarily have to be the same as the author data of the person who actually pushed the changes.
It would theoretically also be possible to choose some constant placeholder credentials for such page build commits, but I did not know whether this would lead to confusion. Furthermore, I did not know what a good placeholder would be. (But this would also remove one step from the build script.)
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org