This is an automated email from the ASF dual-hosted git repository.
erose pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 16d07d5c HDDS-9612. Add CONTRIBUTING.md for the new Ozone website (#54)
16d07d5c is described below
commit 16d07d5cccab479e2017048ff1df2a793e224f60
Author: Ethan Rose <[email protected]>
AuthorDate: Mon Jan 22 10:11:04 2024 -0800
HDDS-9612. Add CONTRIBUTING.md for the new Ozone website (#54)
---
CONTRIBUTING.md | 243 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 76 ++----------------
2 files changed, 248 insertions(+), 71 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..d3854172
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,243 @@
+# Apache Ozone Website Contribution Guide
+
+The Apache Ozone is a top-level Apache project and is licensed under the
[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). The bug
tracking system for Ozone and its website is under the [Apache Jira project
named HDDS](https://issues.apache.org/jira/projects/HDDS/).
+
+This document summarizes the contribution process.
+
+## What Can I Contribute?
+
+- **Issues**: If you find an issue or have an idea for an improvement to the
website, please [file a Jira issue](#filing-jira-issues). Even if you are not
able to fix the issue, please report it so we can find someone who can.
+
+- **Documentation**: You can fix anything from a minor typo, an unclear or
outdated section, or a completely missing page. Most changes in this area can
be done with just basic markdown knowledge.
+
+- **Theme and Styling**: You can help improve the overall appearance of the
Ozone website using standard web development tools like Javascript, React,
HTML, and CSS. You can also create or modify graphics and images used on the
site.
+
+- **Tests**: [HDDS-9601](https://issues.apache.org/jira/browse/HDDS-9601) will
implement a basic set of tests to run as part of CI for the website, but you
can help expand or improve them.
+
+- **Tools**: You can submit improvements to how we use various tools like
pnpm, docker, and Dependabot that are used in the development of the website.
+
+## Filing Jira Issues
+
+Please follow the same [Jira
guidelines](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#jira-guideline)
as the main Ozone project when filing improvements or issues for the website.
Website Jira issues are also under the HDDS project, but can be tagged with
`website` and `documentation` to distinguish them from changes to Ozone itself.
+
+## Modifying the Website
+
+The Apache Ozone Website uses [Docusaurus](https://docusaurus.io/) as a static
site generator. Most simple updates to the website can be done with little
knowledge of Docusaurus, but for more complex modifications to the website or a
better understanding of how it is built, see the Docusaurus
[documentation](https://docusaurus.io/docs) and
[API](https://docusaurus.io/docs/cli).
+
+### Directory Layout
+
+- [docusaurus.config.js](https://docusaurus.io/docs/configuration)
+ - The main configuration file for the docusaurus site.
+
+- [docs](https://docusaurus.io/docs/docs-introduction)
+ - Documentation pages.
+ - The layout of subdirectories determines the layout of the sidebar in the
docs section.
+
+- [versioned_docs](https://docusaurus.io/docs/versioning)
+ - Contains older versions of the documentation.
+ - Only update files in this directory if you need to backport a fix to older
versions of the documentation.
+
+- [sidebars.js](https://docusaurus.io/docs/sidebar/autogenerated)
+ - Configuration of the documentation menu sidebars.
+ - This file should not need to be modified since the menu will be
auto-generated from the directory and file layout.
+
+- [versioned_sidebars](https://docusaurus.io/docs/versioning)
+ - Contains older versions of the documentation sidebars.
+ - Only update files in this directory if you need to backport a fix to older
versions of the documentation.
+
+- [versions.json](https://docusaurus.io/docs/versioning)
+ - Contains a list of all versions of the documentation.
+
+- [static](https://docusaurus.io/docs/static-assets)
+ - Contains non-code files that are directly copied to the build output,
including images.
+
+- **src**
+ - [css](https://docusaurus.io/docs/styling-layout)
+ - Global CSS files loaded by `docusaurus.config.js`
+
+ - [pages](https://docusaurus.io/docs/static-assets)
+ - Static pages outside of the documentation section.
+
+ - **index.js**: The website homepage.
+
+ - [theme](https://docusaurus.io/docs/swizzling)
+ - Contains theme overrides of Docusaurus specific components created with
[swizzling](https://docusaurus.io/docs/swizzling).
+ - Styling of the components is done with [CSS
Modules](https://docusaurus.io/docs/styling-layout#css-modules) which are
stored in the directory with their component.
+
+### Creating or Updating Documentation
+
+#### Page Format
+
+Docusaurus docs are written in markdown. All standard markdown formatting can
be used, but docusaurus provides some additional features to enhance your
pages. Complete details are documented in [Docusaurus markdown
features](https://docusaurus.io/docs/markdown-features), but a high level
summary is provided here:
+
+- The [.mdx file format](https://docusaurus.io/docs/markdown-features/react)
allows you to embed Javascript React components into your markdown for
interactive features.
+
+- [Tabs](https://docusaurus.io/docs/markdown-features/tabs) can show multiple
possibilities succinctly.
+
+- Standard Markdown [Code
blocks](https://docusaurus.io/docs/markdown-features/code-blocks) have extra
features, including:
+ -
[Titles](https://docusaurus.io/docs/markdown-features/code-blocks#code-title)
+ - [Optional line
numbers](https://docusaurus.io/docs/markdown-features/code-blocks#line-numbering)
+ - [Multi-language
tabs](https://docusaurus.io/docs/markdown-features/code-blocks#multi-language-support-code-blocks)
+
+
+- [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
(note, tip, info. warning, danger) optionally with [custom
titles](https://docusaurus.io/docs/markdown-features/admonitions#specifying-title).
+
+- Link to specific headings in pages with [Heading
IDs](https://docusaurus.io/docs/markdown-features/toc#heading-ids)
+
+- Various strategies for adding [graphics to markdown
pages](https://docusaurus.io/docs/markdown-features/assets)
+
+- Inline diagrams with
[Mermaid](https://docusaurus.io/docs/markdown-features/diagrams)
+
+#### Best Practices
+
+Docusaurus provides many options for laying out documentation pages and their
metadata. The following best practices are followed by this repo, and some may
be enforced by CI checks once HDDS-9601 is complete.
+
+- [Number
prefixes](https://docusaurus.io/docs/sidebar/autogenerated#using-number-prefixes)
should be used for all file and sdiebar directory names to enforce their order
in the website and local editors.
+ - Number prefixes will be automatically removed from links in the
Docusaurus build.
+
+- [Category links](https://docusaurus.io/docs/sidebar/items#category-link)
should not be used. They make it easy to miss pages when looking at the sidebar
since it is unclear if they are just a dropdown or also contain documentation.
+
+- Let Docusaurus automatically generate a webpage URL from the file name.
+
+- File names and therefore generated URLs should all be `kebab-case`.
+
+- Let Docusaurus automatically generate the page's title from its top level
markdown heading instead of using `title` in the frontmatter. This is different
from the sidebar label or URL slug.
+
+- Use relative file paths for all links between pages.
+ - This keeps page links pointing to the current version of the
documentation.
+ - See [Markdown Links](https://docusaurus.io/docs/markdown-features/links)
in Docusaurus for more information.
+
+- Use short, succinct labels in the sidebar.
+ - For example, the pages on bucket layouts may be organized as:
+ ```
+ ...
+ Buckets
+ ...
+ Layouts
+ File System Optimized (FSO)
+ Object Store (OBS)
+ ```
+
+ - This avoids a verbose sidebar with duplicate information like this
example:
+ ```
+ ...
+ Buckets
+ ...
+ Bucket Layouts
+ File System Optimized Bucket Layout
+ Object Store Bucket Layout
+ ```
+
+ - Sidebar labels are automatically generated from page titles. To use a
different sidebar label, use the `sidebar_label` property in the page's
frontmatter.
+
+- Don't rely on Ozone specific acronyms in the sidebar. This makes docs
navigation more beginner friendly.
+ - For example, the pages on bucket layouts may be organized as:
+ ```
+ ...
+ Buckets
+ ...
+ Layouts
+ File System Optimized (FSO)
+ Object Store (OBS)
+ ```
+
+ - Which is easier for a new Ozone user to follow than this:
+ ```
+ ...
+ Buckets
+ ...
+ Layouts
+ FSO
+ OBS
+ ```
+
+- Use descriptive page titles.
+ - Pages may be linked directly from other sources and users should be able
to tell what the page is without looking at the sidebar.
+ - There may also be multiple pages about the same topic, for example
Kerberos. Readers should be able to tell which aspect of Kerberos the page is
about to distinguish it from other pages.
+
+ - For example, pages in the security configuration section may be
organized like this:
+ ```
+ Configuration
+ ...
+ Security
+ ...
+ Kerberos
+ ```
+
+ - The sidebar label makes sense because it has the context of the parent
sidebar sections, however the Kerberos page should have a title like
"Configuring Kerberos" instead of just "Kerberos" like its sidebar label.
+
+### Updating Graphics
+
+When adding or updating graphics in the Ozone website, please follow these
guidelines:
+
+- Use SVG files for flat icons with minimal colors. These scale better and are
smaller in size.
+
+- Use PNG files for images that have more colors or complexity.
+
+- Graphics used with documentation should go in the `docs` directory (not the
`static` directory) so that they can be versioned with the rest of the
documentation.
+
+### Updating Theme or Styling
+
+Changing appearance or theme of the website from Docusaurus defaults can be
done with React and CSS. See the Docusaurus documentation on [Styling and
Layout](https://docusaurus.io/docs/styling-layout) and
[Swizzling](https://docusaurus.io/docs/swizzling) for more information. Here
are some general guidelines:
+
+- To update the website homepage, modify `src/pages/index.js` and add or
modify CSS files as needed.
+
+- For global CSS configurations:
+ 1. Create or modify a file in `src/css`.
+ 2. If creating a new file, add it to `config.presets.theme.customCss` in
`docusaurus.config.js` to be loaded.
+
+- For component specific CSS configurations, add a [CSS
module](https://docusaurus.io/docs/styling-layout#css-modules) to the `theme`
subdirectory of the component being modified.
+
+- Make sure styling changes work in both [light and dark
modes](https://docusaurus.io/docs/styling-layout#dark-mode).
+
+### Previewing Your Modifications Locally
+
+Docusaurus supports previewing the website locally. Below are various options
to launch a preview of the site at `localhost:3000` on your machine.
+
+**NOTE** If using the [Docusaurus development
server](https://docusaurus.io/docs/installation#running-the-development-server),
changes to `docusaurus.config.js` may not be automatically reloaded and
require the server to be restarted.
+
+#### Option 1: Docker (Recommended)
+
+The project includes a `Dockerfile` and a `compose.yml` file to build and run
the website in a containerized environment. This creates a docker image called
`ozone-site-dev` with all the dependencies included, and uses it to run the
[Docusaurus development
server](https://docusaurus.io/docs/installation#running-the-development-server).
+
+1. Install [docker](https://docs.docker.com/engine/install/).
+
+2. Install [docker compose](https://docs.docker.com/compose/install/).
+
+3. Run `docker compose up` from the repository root.
+
+4. Preview the website at `localhost:3000` in your browser.
+
+ - Any changes made in the repository will be reflected in the preview.
+
+5. Press `Ctrl+C` or run `docker compose down` to stop the preview.
+
+#### Option 2: pnpm
+
+Build and run the website locally with the `pnpm` package manager.
+
+1. Install [pnpm](https://pnpm.io/installation), which will be used to build
the site.
+
+2. Install dependencies required to build the website by running `pnpm
install` at the website root.
+
+- [**Development
Server**](https://docusaurus.io/docs/installation#running-the-development-server):
This option will start the Docusaurus development server, which allows updates
to website files to be displayed in the browser in real time. It will not
produce a `build` directory with build artifacts.
+
+ 1. Run `pnpm start` from the repository root to start the development server.
+
+ 2. Preview the website at `localhost:3000` in your browser.
+
+ 3. Press `Ctrl+C` to stop the preview.
+
+- [**Local Build**](https://docusaurus.io/docs/installation#build): This
option will do a production build, putting artifacts in the `build` directory.
This can still be previewed locally, but will not automatically reflect changes
to website files.
+
+ 1. Run `pnpm build` from the repository root to build the content.
+
+ 2. Run `pnpm serve` to preview the built website locally.
+
+ 3. Preview the website at `localhost:3000` in your browser.
+
+ 4. Press `Ctrl+C` to stop the preview.
+
+### Contributing Your Modifications
+
+Fork the [apache/ozone-site](https://github.com/apache/ozone-site) repo and
follow the same steps as the main [Ozone contributing
guide](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#contribute-your-modifications)
to create a pull request against the
[apache/ozone-site](https://github.com/apache/ozone-site) repository. the
target branch for the PR should be `HDDS-9225-website-v2` for changes targeting
this new unreleased version of the website.
diff --git a/README.md b/README.md
index 918e674b..23057374 100644
--- a/README.md
+++ b/README.md
@@ -34,75 +34,9 @@ You can preview the current state of the new website at
https://ozone-site-v2.st
- The `asf-site` branch is still holding build artifacts being used to deploy
content from the `master` branch. The new website is not being hosted anywhere,
but can be previewed locally.
-## Local Development
+## Contributing
-Docusaurus supports previewing the website locally. Below are various options
to launch a preview of the site at `localhost:3000` on your machine.
-
-### Option 1: Docker (Recommended)
-
-The project includes a `Dockerfile` and a `compose.yml` file to build and run
the website in a containerized environment. This creates a docker image called
`ozone-site-dev` with all the dependencies included, and uses it to run the
[Docusaurus development
server](https://docusaurus.io/docs/installation#running-the-development-server).
-
-1. Install [docker](https://docs.docker.com/engine/install/).
-
-2. Install [docker compose](https://docs.docker.com/compose/install/).
-
-3. Run `docker compose up` from the repository root.
-
-4. Preview the website at `localhost:3000` in your browser.
-
- - Any changes made in the repository will be reflected in the preview.
-
-5. Press `Ctrl+C` or run `docker compose down` to stop the preview.
-
-### Option 2: pnpm
-
-Build and run the website locally with the `pnpm` package manager.
-
-1. Install [pnpm](https://pnpm.io/installation), which will be used to build
the site.
-
-2. Install dependencies required to build the website by running `pnpm
install` at the website root.
-
-- [**Development
Server**](https://docusaurus.io/docs/installation#running-the-development-server):
This option will start the Docusaurus development server, which allows updates
to website files to be displayed in the browser in real time. It will not
produce a `build` directory with build artifacts.
-
- 1. Run `pnpm start` from the repository root to start the development server.
-
- 2. Preview the website at `localhost:3000` in your browser.
-
- 3. Press `Ctrl+C` to stop the preview.
-
-- [**Local Build**](https://docusaurus.io/docs/installation#build): This
option will do a production build, putting artifacts in the `build` directory.
This can still be previewed locally, but will not automatically reflect changes
to website files.
-
- 1. Run `pnpm build` from the repository root to build the content.
-
- 2. Run `pnpm serve` to preview the built website locally.
-
- 3. Preview the website at `localhost:3000` in your browser.
-
- 4. Press `Ctrl+C` to stop the preview.
-
-### Updating the Website
-
-The following files can be modified to change various aspects of the website:
-
-- `docusaurus.config.js`
- - The main configuration file for the docusaurus site.
- - See https://docusaurus.io/docs/configuration
-
-- `sidebars.js`
- - Configuration of the documentation menu sidebars.
- - This file should not need to be modified since the menu will be
auto-generated from the directory and file layout.
- - See https://docusaurus.io/docs/sidebar/autogenerated
-
-- `static`
- - Contains non-code files that are directly copied to the build output.
- - See https://docusaurus.io/docs/static-assets
- - `static/img`
- - Directory for all images needed to build the site.
-
-- `docs`
- - Documentation pages.
- - See https://docusaurus.io/docs/create-doc
-
-- `src/pages`
- - Static pages outside of the documentation section.
- - See https://docusaurus.io/docs/creating-pages
\ No newline at end of file
+Please see `CONTRIBUTING.md` for information about
+- [Directory layout](./CONTRIBUTING.md#directory-layout)
+- [Previewng the website
locally](./CONTRIBUTING.md#previewing-your-modifications-locally)
+- [Filing Issues](./CONTRIBUTING.md#filing-jira-issues)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
