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 7638cb95 HDDS-10449. Add quick start to the top of contributing guide.
(#83)
7638cb95 is described below
commit 7638cb95781da5a1899c2c4cb8f49fa6e475cd19
Author: Ethan Rose <[email protected]>
AuthorDate: Mon Apr 15 17:35:53 2024 -0700
HDDS-10449. Add quick start to the top of contributing guide. (#83)
---
CONTRIBUTING.md | 35 ++++++++++++++++++++++++++++-------
README.md | 1 +
2 files changed, 29 insertions(+), 7 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9c2f1e2b..bfbd8f02 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,9 +1,28 @@
# 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/).
+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.
+## Quick Start
+
+1. Review the main [Ozone contributing
guide](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#contribute-your-modifications).
Contributing to the new website follows a similar process with a few
differences:
+ - You should fork the
[apache/ozone-site](https://github.com/apache/ozone-site) repo instead of the
main [apache/ozone](https://github.com/apache/ozone) repo.
+ - You should enable the `ci` workflow on your fork, which will run tests
on your changes before submitting a pull request.
+ - Your local branch containing changes for the new website should be based
off of the
[HDDS-9225-website-v2](https://github.com/apache/ozone-site/tree/HDDS-9225-website-v2)
branch.
+
+2. Use your favorite editor to write markdown content under the [docs/](docs/)
and [src/pages/](src/pages/) directories.
+ - A good option is [Visual Studio Code](https://code.visualstudio.com/)
with
[markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
and
[cspell](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
plugins, which will automatically detect the website's configuration files and
give feedback as you type.
+
+3. Preview your changes locally by running `docker compose up` and opening
`localhost:3000` in your browser.
+ - Make sure [Docker](https://docs.docker.com/engine/install/) and [Docker
Compose](https://docs.docker.com/compose/install/) are installed on your system.
+ - If you need to update the dependencies in your Docker image at any time,
run `docker compose up --build` to create an updated image.
+
+4. 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](https://github.com/apache/ozone-site/tree/HDDS-9225-website-v2)
for changes targeting this new unreleased version of the website.
+
+⬇️ Continue reading for more details, helpful tips, and advanced usage. ⬇️
+
## 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.
@@ -12,7 +31,7 @@ This document summarizes the contribution process.
- **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.
+- **Tests**: [HDDS-9601](https://issues.apache.org/jira/browse/HDDS-9601) is
the parent Jira for implementing tests to run as part of CI for the website.
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.
@@ -89,7 +108,7 @@ Docusaurus docs are written in markdown. All standard
markdown formatting can be
#### 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.
+Docusaurus provides many options for laying out documentation pages and their
metadata. The following best practices are followed by this repo, and some are
enforced by GitHub actions CI checks.
- [Number
prefixes](https://docusaurus.io/docs/sidebar/autogenerated#using-number-prefixes)
should be used for all file and sidebar directory names to enforce their order
in the website and local editors.
- Number prefixes will be automatically removed from links in the Docusaurus
build.
@@ -172,13 +191,13 @@ Docusaurus provides many options for laying out
documentation pages and their me
#### Spelling
-The file names and content of all markdown pages are checked for spelling
mistakes using [cspell](https://cspell.org/) as part of GitHub actions.
Spelling can also be checked locally by running the script
*.github/scripts/spelling.sh*. This requires you to have pnpm's dev
dependencies installed on your machine for cspell to work (run `pnpm install
--dev`).
+The file names and content of all markdown pages are checked for spelling
mistakes using [cspell](https://cspell.org/) as part of GitHub actions.
Spelling can also be checked locally by running the script
[.github/scripts/spelling.sh](.github/scripts/spelling.sh). This requires you
to have pnpm's dev dependencies installed on your machine for cspell to work
(run `pnpm install --dev`).
**If spell check fails for words that are correct but not recognized:**
-- Option 1: If the word is relevant for the whole Ozone project, add it to the
`words` list in *cspell.yaml* so that it is considered valid.
+- **Option 1:** If the word is relevant for the whole Ozone project, add it to
the `words` list in *cspell.yaml* so that it is considered valid.
-- Option 2: If the word is only relevant for one specific page, add an [inline
directive](https://cspell.org/configuration/document-settings/) as a comment in
the markdown front matter of that page only.
+- **Option 2:** If the word is only relevant for one specific page, add an
[inline directive](https://cspell.org/configuration/document-settings/) as a
comment in the markdown front matter of that page only.
### Updating Graphics
@@ -206,6 +225,8 @@ Changing appearance or theme of the website from Docusaurus
defaults can be done
### Package Management
+**NOTE:** pnpm is **not** required for local website previews. Simply run
`docker compose up` if a local preview is the only functionality you need.
+
The website uses [pnpm](https://pnpm.io/) as a package manager. This is the
same package manager used to build
[Recon](https://github.com/apache/ozone/tree/master/hadoop-ozone/recon/src/main/resources/webapps/recon/ozone-recon-web).
Basic knowledge required to maintain the website's dependencies is outlined
here. See [pnpm docs](https://pnpm.io/pnpm-cli) for complete usage.
#### Relevant Files
@@ -228,7 +249,7 @@ This file contains exact version information of all
dependencies required to bui
Currently all `@docusaurus/*` packages are pinned to an exact version for
website stability.
-#### Command Cheat-Sheet
+#### `pnpm` Command Cheat-Sheet
- **To install all packages after cloning the repo**: `pnpm install`
diff --git a/README.md b/README.md
index 923604f8..06d7b7a6 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,7 @@ You can preview the current state of the new website at
https://ozone-site-v2.st
Please see `CONTRIBUTING.md` for information about
+- [Quick start](./CONTRIBUTING.md#quick-start)
- [Directory layout](./CONTRIBUTING.md#directory-layout)
- [Previewing 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]
