From e62feb4d2d189a5e2aed6b91af2a4c908cd3840f Mon Sep 17 00:00:00 2001 From: Kenny Carlile Date: Tue, 11 Jun 2024 17:14:41 -0700 Subject: [PATCH] Updating build scripts and technical documentation --- .scripts/build.sh | 11 ++-- .scripts/package-check.sh | 3 +- README.md | 36 +++--------- docs/code-owner-docs.md | 112 ++++++++++++++++++++++++++++++++++++++ package.json | 2 - 5 files changed, 128 insertions(+), 36 deletions(-) create mode 100644 docs/code-owner-docs.md diff --git a/.scripts/build.sh b/.scripts/build.sh index 57fc73b..67b1e19 100755 --- a/.scripts/build.sh +++ b/.scripts/build.sh @@ -11,6 +11,12 @@ LOCAL_PATH=$(dirname "$0") echo "< Beginning Guitar Diagrams JS build script..." echo "" +echo ">> Beginning package.json linting..." +npx publint +echo ">> Ending package linting." +echo "" + + echo ">> Beginning package checking..." source "$LOCAL_PATH/package-check.sh" echo "<< Ending package checking." @@ -40,9 +46,4 @@ npm install ./ echo "<< Ending npm install." echo "" -echo ">> Beginning npm run build..." -npm run build -echo "<< Ending npm run build." -echo "" - echo "< Ending Guitar Diagrams JS build script." diff --git a/.scripts/package-check.sh b/.scripts/package-check.sh index 5b96673..08ac685 100755 --- a/.scripts/package-check.sh +++ b/.scripts/package-check.sh @@ -7,8 +7,9 @@ echo "" echo "< Beginning Guitar Diagrams JS package check script..." echo "" -echo ">> Beginning linting..." +echo ">> Beginning package.json linting..." npx publint +echo ">> Ending package linting." echo "" echo "< Ending Guitar Diagrams JS package check script." diff --git a/README.md b/README.md index 969546f..f6e059d 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,9 @@ GitHub profile: [@KCarlile](https://github.com/KCarlile) Please see the following pages for more information: - [`README.md`](README.md): this page -- [`docs/index.md`](docs/index.md): API usage documentation +- [`docs/index.md`](docs/index.md): main landing page for project documentation +- [`docs/api-docs.md`](docs/api-docs.md): API usage documentation +- [`docs/code-owner-docs.md`](docs/code-owner-docs.md): technical documentation for code owners - [`docs/examples/index.html`](docs/examples/index.html): usage examples - [`docs/CODE_OF_CONDUCT.md`](docs/CODE_OF_CONDUCT.md): code of conduct for contributing members - [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md): instructions for contributing to the project @@ -102,9 +104,9 @@ If you want to use a CDN-hosted package (e.g., Guitar Diagrams JS on JSDelivr at Be sure to add some target HTML element to your page with a matching ID (`gdj1.addCanvas('diagram-1');` where `diagram-1` is the ID) in your JS code so Guitar Diagrams JS knows where to add your drawing: - ```html -
- ``` +```html +
+``` #### Option 3: Manual Installation via Local Copies @@ -143,31 +145,9 @@ For more information, please see the [`docs/index.md`](docs/index.md) and ['docs ## Technical Information for Code Owners -### Building, Packaging, and Releasing - -#### Local Builds and Releases - -Before committing any code changes or when creating a new release, run `node install` in the project to update the `package-lock.json` file. You can also run the `.scripts/build.sh` bash script to run this step, which performs other necessary checks and file management. - -```bash -npm run build-local -``` - -The `.scripts/build.sh` script is defined in the `package.json;` file as `build-local`, so it can be run with `npm run build-local`. That script runs: - -- `package.json` linting -- Code linting on HTML, JS, CSS, and Markdown -- Copies the `*.jsm` files from `src/*` to `docs/examples/js/guitar-diagrams-js/*` so the examples on `docs/examples/index.html` can reference those files. - -#### Releases - -Next, you will stage, commit, and push the changes to GitHub. Once the code is in the GitHub repo, create a PR into the `main` branch, if necessary. - -To create a release, use the [Release page](https://github.com/KCarlile/guitar-diagrams-js/releases) to create a new release which will kick off a new package deployment using the GitHub Action workflow defined in `.github/workflows/release-package.yml`. Once the workflow has completed successfully, the package will be hosted on the [Packages page](https://github.com/KCarlile/guitar-diagrams-js/pkgs/npm/guitar-diagrams-js). - -See also [`docs/examples/js/guitar-diagrams-js/README.md`](docs/examples/js/guitar-diagrams-js/README.md) for information about symlinks for local testing and demo deployment information. +See [`docs/code-owners.md`](docs/code-owners.md) for documentation related to development and deployment. -### Dependency Requirements +## Dependency Requirements There are no specific requirements[1](#footnotes) for dependencies to use Guitar Diagrams JS other than the standard browser compatibility considerations with CSS, JavaScript, and HTML 5's `` tag. Browser compatibility for the `` tag can be found on [the MDN `` page](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas#browser_compatibility). diff --git a/docs/code-owner-docs.md b/docs/code-owner-docs.md new file mode 100644 index 0000000..46da4f5 --- /dev/null +++ b/docs/code-owner-docs.md @@ -0,0 +1,112 @@ +# Code Owner Documentation + +This documentation page is for code owners to understand the technical details of the project and the release process. + +## Table of Contents + +- [Code Owner Documentation](#code-owner-documentation) + - [Table of Contents](#table-of-contents) + - [Directory Structure](#directory-structure) + - [Code Architecture](#code-architecture) + - [Scripts](#scripts) + - [`build.sh`](#buildsh) + - [`linting.sh`](#lintingsh) + - [`package-check.sh`](#package-checksh) + - [`super-linter.sh`](#super-lintersh) + - [Building, Packaging, and Releasing](#building-packaging-and-releasing) + - [Local Builds and Releases](#local-builds-and-releases) + - [Releases](#releases) + +## Directory Structure + +This section outlines the directory structure of the project. + +- `.config/`: Configuration files. + - `linters/`: Configuration files for linters. + - `stylelint.config.json`: Configuration file for CSS linting used by Super-Linter. +- `.github/`: Files used by GitHub. + - `ISSUE_TEMPLATE/`: Markdown files for GitHub issue templates. + - `01-bug-report.md`: Template for GitHub issues of type bug. + - `02-feature-request.md`: Template for GitHub issues of type feature request. + - `config.yml`: GitHub Actions config. + - `workflows/`: YML files to define GitHub Actions. + - `demo-hosting.yml`: GitHub Actions workflow to deploy `examples/` content to GoDaddy hosting for demos. + - `linting.yml`: GitHub Actions workflow for linting codebase. + - `release-package.yml`: GitHub Actions workflow to create an NPM package for release and hosting on GitHub. +- `.scripts/`: Local scripts used for development, packaging, and releases. + - `build.sh`: Build script to prepare package for deployment by running linting and deployment tasks. Run with `npm run build`. + - `linting.sh`: Script to run Super-Linter for HTML, JS, CSS, and Markdown linting. Runs as part of the `build.sh` script. + - `package-check.sh`: Script to run local linting against `package.json`. Runs as part of the `build.sh` script. + - `super-linter.sh`: Script to run local linting. Called by `linting.sh`. Runs as part of the `build.sh` script. +- `docs/`: Documentation and examples for the project. + - `examples/`: Example usage for the project. + - `css/`: CSS files for `index.html` examples page. + - `styles.css`: Defines styles for `index.html`, if necessary. + - `js/`: JS files for `index.html` examples page. + - `guitar-diagrams-js/`: Copied project JavaScript (`*.mjs`) files go into this directory when copied here by `.scripts/build.sh`. + - `main.js`: Used by `../index.html` for examples; references the project's JavaScript files copied into `guitar-diagrams-js/` by `.scripts/build.sh`. + - `testing.js`: Used by `../testing.html` for development and testing. + - `api-docs.md`: Detailed API documentation for using the project library. + - `CODE_OF_CONDUCT.md`: Community guidelines for communications and actions. + - `code-owner-docs.md`: This document. + - `CONTRIBUTING.md`: Community guidelines for contributing to the project. + - `index.md`: Main documentation landing page. + - `index.html`: Documentation with demonstrations of examples for how to use the projet. + - `testing.html`: Testing page used for development. +- `src/`: Contains development files. + - `guitar-diagrams.mjs`: Main entry point for the project. + - `guitar-diagrams-config.mjs`: Config object for defining the library's behavior. + - `guitar-diagrams-marker.mjs`: Object for a marker instance. +- `.gitignore`: File patterns to ignore for Git. +- `.npmignore`: File patterns to ignore for NPM. +- `.npmrc`: Config values for NPM deployments. +- `LICENSE`: Software license file (GPL-3.0) +- `package.json`: NPM package config. +- `package-lock.json`: NPM dependency tree, automatically generated by NPM from `package.json`. +- `README.md`: Main/intro documentation for the project. + +## Code Architecture + +The `GuitarDiagramsJS` class is where site builders will start with leveraging the library. Every interaction happens with a `GuitarDiagramsJS` object, which then leverages the `GuitarDiagramsJSConfig` and the `GuitarDiagramsJSMarker` classes to for modularity and encapsulation. Site builders never need to know about the `GuitarDiagramsJSConfig` and `GuitarDiagramsJSMarker` classes. + +## Scripts + +The `.scripts/` directory contains Bash scripts for local development, build, and deployment tasks. + +### `build.sh` + +The build script prepares the project for release and deployment by performing these actions: + +1. Call `package-check.js` to validate the `package.json` syntax. +1. Call `linting.sh` to check for HTML, CSS, JS, and Markdown syntax errors. +1. Copy `*.mjs` files from `src/` to `docs/examples/js/guitar-diagrams-js/` for use by `docs/examples/index.html`. +1. Calls `npm install ./` to add any NPM dependencies and update the `package-lock.json` file. + +The build script can be executed by running `npm run build` in the root of the project. + +### `linting.sh` + +This script calls the `super-linter.sh` script (see below) and scans the output for any linting errors. This can be run as part of the `build.sh` script by running `npm run build` from the root of the project. + +### `package-check.sh` + +This script calls the `npx publint` to check the `package.json` file for correctness. This can be run as part of the `build.sh` script by running `npm run build` from the root of the project. + +### `super-linter.sh` + +This script starts a Docker container to run a local version of Super-Linter for linting HTML, CSS, JS, and Markdown. This can be run as part of the `build.sh` script by running `npm run build` from the root of the project. + +## Building, Packaging, and Releasing + +### Local Builds and Releases + +- When all of your code changes are complete, AND... +- You've executed `.scripts/build.sh`, AND... +- You're not seeing any errors in the output of the build script, THEN... +- Commit your changes and push to GitHub, then issue a PR into the `develop` branch for testing. + +## Releases + +When you have enough features and bugs merged to justify a release, create a PR from the `develop` branch into `main` branch. Once that is merged, use the [Release page](https://github.com/KCarlile/guitar-diagrams-js/releases) to create a new release which will kick off a new package deployment using the GitHub Action workflow defined in `.github/workflows/release-package.yml`. Once the workflow has completed successfully, the package will be hosted on the [Packages page](https://github.com/KCarlile/guitar-diagrams-js/pkgs/npm/guitar-diagrams-js). + +See also [`docs/examples/js/guitar-diagrams-js/README.md`](docs/examples/js/guitar-diagrams-js/README.md) for information about symlinks for local testing and demo deployment information. diff --git a/package.json b/package.json index 3d28117..4b96e41 100644 --- a/package.json +++ b/package.json @@ -12,9 +12,7 @@ "doc": "docs" }, "scripts": { - "package-check": ".scripts/package-check.sh", "build": ".scripts/build.sh", - "build-local": ".scripts/build-local.sh", "test": "exit 0" }, "repository": {