Fwd: [GitHub] [db-jdo-site] tobous commented on a change in pull request #14: Update README.md
Hi Tobous, Thanks for your careful review and for these updates. I think we're now done with the README, modulo finding all of the missing full stops and until we change the name of the master branch... Craig > Begin forwarded message: > > From: GitBox > Subject: [GitHub] [db-jdo-site] tobous commented on a change in pull request > #14: Update README.md > Date: April 4, 2021 at 5:15:23 AM PDT > To: jdo-dev@db.apache.org > Reply-To: jdo-dev@db.apache.org > > > tobous commented on a change in pull request #14: > URL: https://github.com/apache/db-jdo-site/pull/14#discussion_r606792654 > > > > ## > File path: README.md > ## > @@ -7,18 +7,21 @@ 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 > section [Publishing the Site](#publishing-the-site). > > The site can be built by calling `mvn clean compile`. This generates the HTML > files in `target/site`. > +Most of the site will work with the exception of the javadoc file downloads. > +If needed, call `mvn package`. This copies the javadoc files to > `target/site`. > +The site can then be viewed by opening the local file > `target/site/index.html` in a browser. > > ### Adding Javadoc > > The site contains a packaged version of the JDO API javadoc. It can be > updated as follows: > > * Create the javadoc jar (e.g. jdo-api-3.2-javadoc.jar) in the db-jdo > repository by calling `mvn clean install -Papache-release` in the api > submodule. > -* Create a new folder under docs e.g. docs/api32. > -* Copy the javadocs jar info the new folder: e.g. `cp > jdo-api-3.2-javadoc.jar docs/api32`. > -* Create a new subfolder docs/api32/jdo-api-3.2-javadoc > +* Create a new folder under docs e.g. `src/main/resources/javadoc/api32`. > > Review comment: > ```suggestion > * Create a new folder under in the javadoc resources directory, e.g. > `src/main/resources/javadoc/api32`. > ``` > > ## > File path: README.md > ## > @@ -32,15 +35,27 @@ This repository contains the JDO website source. > > * The AsciiDoc sources can be found in `src/main/asciidoc`. > * The website menu is defined in `src/main/template`. > - * The converter for migrating the old HTML files to AsciiDoc can be found > in `src/main/java` > + * The converter for migrating the old HTML files to AsciiDoc can be found > in `src/main/java`. > + * Additional pre-compiled resources are located in `src/main/resources`. > > -Contributions to this repository follow the default [GitHub > workflow](https://guides.github.com/introduction/flow/) using > [forks](https://guides.github.com/activities/forking/). > +Contributions to this repository follow the default [GitHub > workflow](https://guides.github.com/introduction/flow/) > +using [forks](https://guides.github.com/activities/forking/). > > 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. > - * Commit the source changes (not the build artifacts) and open a pull > request. > + * Build the site (see [above](#building-the-site) and verify the generated > website by viewing `target/site/index.html` locally with a web browser. > > Review comment: > ```suggestion >* Build the site (see [above](#building-the-site)) and verify the > generated website by viewing `target/site/index.html` locally with a web > browser. > ``` > > > > > -- > 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: > us...@infra.apache.org > > Craig L Russell c...@apache.org
[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_r606792654 ## File path: README.md ## @@ -7,18 +7,21 @@ 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 section [Publishing the Site](#publishing-the-site). The site can be built by calling `mvn clean compile`. This generates the HTML files in `target/site`. +Most of the site will work with the exception of the javadoc file downloads. +If needed, call `mvn package`. This copies the javadoc files to `target/site`. +The site can then be viewed by opening the local file `target/site/index.html` in a browser. ### Adding Javadoc The site contains a packaged version of the JDO API javadoc. It can be updated as follows: * Create the javadoc jar (e.g. jdo-api-3.2-javadoc.jar) in the db-jdo repository by calling `mvn clean install -Papache-release` in the api submodule. -* Create a new folder under docs e.g. docs/api32. -* Copy the javadocs jar info the new folder: e.g. `cp jdo-api-3.2-javadoc.jar docs/api32`. -* Create a new subfolder docs/api32/jdo-api-3.2-javadoc +* Create a new folder under docs e.g. `src/main/resources/javadoc/api32`. Review comment: ```suggestion * Create a new folder under in the javadoc resources directory, e.g. `src/main/resources/javadoc/api32`. ``` ## File path: README.md ## @@ -32,15 +35,27 @@ This repository contains the JDO website source. * The AsciiDoc sources can be found in `src/main/asciidoc`. * The website menu is defined in `src/main/template`. - * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java` + * The converter for migrating the old HTML files to AsciiDoc can be found in `src/main/java`. + * Additional pre-compiled resources are located in `src/main/resources`. -Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/) using [forks](https://guides.github.com/activities/forking/). +Contributions to this repository follow the default [GitHub workflow](https://guides.github.com/introduction/flow/) +using [forks](https://guides.github.com/activities/forking/). 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. - * Commit the source changes (not the build artifacts) and open a pull request. + * Build the site (see [above](#building-the-site) and verify the generated website by viewing `target/site/index.html` locally with a web browser. Review comment: ```suggestion * Build the site (see [above](#building-the-site)) and verify the generated website by viewing `target/site/index.html` locally with a web browser. ``` -- 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: us...@infra.apache.org
[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_r557339854 ## 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`](./.github/workflows/deploy-site.yml) which builds the site in `db-jdo-site/target/` via `mvn clean install`. ``` 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: us...@infra.apache.org
[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_r557339854 ## 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`](.github/workflows/deploy-site.yml) which builds the site in `db-jdo-site/target/` via `mvn clean install`. ``` 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: us...@infra.apache.org
[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 sim
