[GitHub] [incubator-yunikorn-site] wilfred-s commented on a change in pull request #46: [YUNIKORN-348] update readme for release update

[GitBox <gi...@apache.org>]

wilfred-s commented on a change in pull request #46:
URL: https://github.com/apache/incubator-yunikorn-site/pull/46#discussion_r617289550



##########
File path: README.md
##########
@@ -63,42 +61,121 @@ yarn run start
 ```
 A local build will also generate the website in the `build` directory same as with the script.
 
-## Add / Update documents
-
+## Updating the site
 The website is built based using [docusaurus-v2](https://v2.docusaurus.io/docs/docs-introduction). 
 The pages and documentation are written in MD file format, the data required is located at:
-- src/pages: the non-versioned pages of the site
-- docs: the master version of the documentation
-- sidebars.js: change this file if you need to update the layout of the documentation
+* `docusaurus.config.js` the main site layout and menu definition
+* `src/pages` the non-versioned static pages of the site
+* `static` images not used in the documentation 
+* `docs` the master version of the documentation
+* `sidebars.js` the layout of the documentation menu
+
+The directories `versioned_docs` and `versioned_sidebars` contain the versioned copies of the documentation and the layout.
+See [Documentation](#Documentation) for maintenance recommendations.
+
+For advanced updates, including style, theme, etc, please refer to the docusaurus documentation.
 
+## Static pages
+Static pages form a small but crucial part of the site.
+The following pages are part of the static content:
+* roadmap 
+* download information
+* community pages
+
+The top menu is defined in the `docusaurus.config.js`.
+New pages that are added which need to be accessible from the menu must be added 
+The Apache links are only defined as part of the site layout and are not backed by any pages.
+
+## Documentation
 Images that are part of a documentation page must be located in the `assets` directory as part of the documents, i.e. `docs/assets`.
 All other images that are used, for instance the homepage and menu, that do not change when or if the documentation is updated/versioned must be located in the `static/img` directory.   
 
-The versioned documents and side bars should only be updated to fix errors. The versioned documentation and side bar are located in: 
+The versioned documents and sidebars should only be updated to fix errors that cannot wait for a release.
+The versioned documentation and sidebar are located in: 
 - versioned_docs: the released version of documentation
 - versioned_sidebars: the sidebars for the corresponding released documentation
 
-For advanced updates, including style, theme, etc, please refer to the docusaurus documentation.
+Normal documentation maintenance must be performed by updating the non versioned documentation.
+New pages are added by:
+* adding a Markdown file
+* updating the `sidebar.js` file
 
-## Release a new version
-This step requires you to have yarn locally installed and is only needed when a new release is approved by the community.
+The page file must contain:
+* id and title definition (docusaurus syntax)
+* Apache license
 
+The id is used by docusaurus to link the page to the specific point in the documentation menu. 
+The title is displayed in the menu.  
+```
+---
+id: MyPageID
+title: My new documentation page
+---
+```
+Pages can be grouped in categories in the sidebar.
+The category should be represented as directories in the source tree. 
+
+## Releasing a new version
+Releasing a new version requires you to have yarn locally installed.
+This should only be run by a release manager or on request of the release manager.
+
+Pre-requisites: 
+* The release must have been approved via the release process.
+* The source archive file and signatures must have been uploaded to the Apache locations.
+* The docker convenience images must have been pushed to the Apache docker hub.   
+
+Open a PR and commit all the changes below to the **master** branch, once the auto-build is done, the new documentation will be presented on the website.
+
+### Version the documentation
+Documentation versioning uses the simple **MAJOR.MINOR.PATCH** semver version of the release. 
+This means no letters, release candidate tags or anything like that:  
 ```shell script
 yarn release 0.9.0
 ```
 This command will snapshot all the docs from the current `docs` directory, and copy all files to another new directory
 under `versioned_docs`, e.g `versioned_docs/version-0.9.0`.
 A similar copy will be generated for the sidebar under `versioned_sidebars` that belongs to the documentation version.
 
-Open a PR and commit these changes to the **master** branch, once the auto-build is done, the new documentation will be presented on the website.
+This process will also update the `version.json` file in the root and add the new release as a line item.
 
-## Deploy website
+### Release announcement
+The release announcement is a static Markdown file added to the directory `src/pages/release-announce`.
+The file name is the same a simple semver version of the release:
+``` 
+src/pages/release-announce/0.9.0.md
+```
+The page is in Markdown format and should follow the example of the already existing pages:
+* id and title definition (docusaurus syntax)
+* Apache license
+* Following headings
+  * Title (level 1)
+  * Overview of the release (level 2)
+  * Highlights (level 2)
+    Chosen highlights at level 3 heading
+  * Community update (level 2)
+
+### Update the download page
+The download page contains the link to the Apache source download, signatures etc.
+The table on the page has a specific layout that is correctly rendered after going through the docusaurus build.
+Please do not change the release entry layout in the table.
+
+First step is to update the `latest release` line to the correct version.  
+Second step is to update the table: copy an existing entry and change the links and details to point to the new release.
+All links must be updated:
+* 3 for the download (source tar, checksum and signature)
+* 2 for the docker images (scheduler and admission controller)

Review comment:
       fixed




-- 
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