Merge pull request #43 from KCarlile/develop

Develop into main

.github/workflows/demo-hosting.yml

@@ -27,25 +27,3 @@ jobs:
           **/node_modules/**
           testing.html
           js/testing.js
-    
-    - name: Upload *.js files to overwrite symlinks
-      uses: SamKirkland/[email protected]
-      with:
-        server: 107.180.58.30
-        username: ${{ secrets.ftp_username }}
-        password: ${{ secrets.ftp_password }}
-        local-dir: ./
-        server-dir: guitar-diagrams-js/js/guitar-diagrams-js/
-        exclude: |
-          **/.config/**
-          **/.git*
-          **/.git*/**
-          **/.scripts/**
-          **/docs/**
-          **/node_modules/**
-          .gitignore
-          .npmrc
-          LICENSE
-          package.json
-          package-lock.json
-          README.md

.gitignore

@@ -1,3 +1,5 @@
 .vscode/*
 .DS_Store
 Thumbs.db
+node_modules
+node_modules/*

.npmignore

@@ -0,0 +1,13 @@
+.vscode/*
+.DS_Store
+Thumbs.db
+node_modules
+node_modules/*
+.config
+.config/*
+.github
+.github/*
+.scripts
+.scripts/*
+.vscode
+.vscode/*

.scripts/build.sh

@@ -11,9 +11,34 @@ LOCAL_PATH=$(dirname "$0")
 echo "< Beginning Guitar Diagrams JS build script..."
 echo ""
 
-echo ">> Beginning Super-Linter (local) run..."
-bash -x "$LOCAL_PATH/"super-linter.sh
-echo "<< Ending Super-Linter (local) run."
+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."
+echo ""
+
+echo ">> Beginning linting..."
+source "$LOCAL_PATH/linting.sh"
+RETURN_CODE=$?
+echo "<< Ending linting."
+echo ""
+
+# If linting fails, it shouldn't reach this point, but just in case...
+if (( RETURN_CODE > 0 )); then
+    echo "[ERROR] Linting failed: see above or run linting.sh with the argument "verbose" for full logs."
+    exit 1
+fi
+
+echo ">> Beginning build for examples..."
+SRC_SCRIPTS="$LOCAL_PATH/../src/*.mjs"
+TARGET_PATH="$LOCAL_PATH/../docs/examples/js/guitar-diagrams-js/"
+cp $SRC_SCRIPTS $TARGET_PATH
+echo "<< Ending build for examples."
 echo ""
 
 echo ">> Beginning npm install..."

.scripts/linting.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# Argument 1: "verbose" enables full log printing
+# usage: $ ./linting.sh verbose
+
+echo ""
+echo "########################################"
+echo "# Guitar Diagrams JS linting script"
+echo "########################################"
+echo ""
+
+SHOW_FULL_LOG="$(echo "$1" | tr a-z A-Z)"
+LOCAL_PATH=$(dirname "$0")
+
+echo "< Beginning Guitar Diagrams JS linting script..."
+echo ""
+
+echo ">> Beginning Super-Linter (local) run..."
+FULL_LOG="$(bash -x "$LOCAL_PATH/"super-linter.sh)"
+LOG="$(echo "${FULL_LOG}" | grep -e "ERROR_COUNTER for CSS" -e "ERROR_COUNTER for HTML" -e "ERROR_COUNTER for JAVASCRIPT_ES" -e "ERROR_COUNTER for MARKDOWN")"
+
+if [ "$SHOW_FULL_LOG" == "VERBOSE" ]; then
+    echo "========================================"
+    echo "= BEGIN full log..."
+    echo "========================================"
+    echo "$FULL_LOG"
+    echo "========================================"
+    echo "= END full log."
+    echo "========================================"
+fi
+
+echo "<< Ending Super-Linter (local) run."
+echo ""
+
+echo "< Ending Guitar Diagrams JS linting script."
+echo ""
+
+echo "$LOG"
+echo ""
+
+REGEX=".*ERROR_COUNTER for (CSS|HTML|JAVASCRIPT_ES|MARKDOWN): ([0-9]+)"
+FAILURES=0
+
+while IFS= read -r LINE; do
+    if [[ "$LINE" =~ $REGEX ]]; then
+        LANGUAGE=${BASH_REMATCH[1]}
+        ERROR_COUNT=${BASH_REMATCH[2]}
+
+        if [ "$ERROR_COUNT" -eq "0" ]; then
+            echo "${BASH_REMATCH[1]}: PASSED"
+        else
+            FAILURES=$((FAILURES + 1))
+            echo "${BASH_REMATCH[1]} errors: ${BASH_REMATCH[2]}"
+        fi
+    fi
+done <<< "$LOG"
+
+if (( FAILURES > 0 )); then
+    echo "[ERROR] Failures found: ${FAILURES} (see above)"
+    exit 1
+fi

.scripts/package-check.sh

@@ -0,0 +1,15 @@
+echo ""
+echo "########################################"
+echo "# Guitar Diagrams JS package check script"
+echo "########################################"
+echo ""
+
+echo "< Beginning Guitar Diagrams JS package check script..."
+echo ""
+
+echo ">> Beginning package.json linting..."
+npx publint
+echo ">> Ending package linting."
+echo ""
+
+echo "< Ending Guitar Diagrams JS package check script."

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
-   <div id="diagram-1"></div>
-   ```
+```html
+<div id="diagram-1"></div>
+```
 
 #### Option 3: Manual Installation via Local Copies
 
@@ -143,17 +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
-
-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. (There are currently no other build steps included.)
-
-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<sup>[1](#footnotes)</sup> for dependencies to use Guitar Diagrams JS other than the standard browser compatibility considerations with CSS, JavaScript, and HTML 5's `<canvas>` tag. Browser compatibility for the `<canvas>` tag can be found on [the MDN `<canvas>` page](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas#browser_compatibility).
 

docs/code-owner-docs.md

@@ -0,0 +1,114 @@
+# 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.

docs/examples/index.html

@@ -248,6 +248,7 @@ <h5>Code</h5>
             </div>
         </div>
         <!-- BEGIN: custom script include for Guitar Diagrams JS -->
+        <script src="../../src/guitar-diagrams.mjs" type="module"></script>
         <script src="./js/main.js" type="module"></script>
         <!-- END: custom script include for Guitar Diagrams JS -->
         <!-- BEGIN: CDN include for Bootstrap -->

guitar-diagrams.js → docs/examples/js/guitar-diagrams-js/guitar-diagrams.mjs

@@ -8,8 +8,8 @@
  * @link https://github.com/KCarlile
  */
 
-import { GuitarDiagramsJSConfig } from './guitar-diagrams-config.js';
-import { GuitarDiagramsJSMarker } from './guitar-diagrams-marker.js';
+import { GuitarDiagramsJSConfig } from './guitar-diagrams-config.mjs';
+import { GuitarDiagramsJSMarker } from './guitar-diagrams-marker.mjs';
 
 /**
  * Class representing primary Guitar Diagrams JS functionality.

docs/examples/js/main.js

@@ -8,7 +8,7 @@
  * @link https://github.com/KCarlile
  */
 
-import { GuitarDiagramsJS } from './guitar-diagrams-js/guitar-diagrams.js';
+import { GuitarDiagramsJS } from './guitar-diagrams-js/guitar-diagrams.mjs';
 
 // ========== BEGIN example 1
 let gdj1 = new GuitarDiagramsJS();

docs/examples/js/testing.js

@@ -8,7 +8,7 @@
  * @link https://github.com/KCarlile
  */
 
-import { GuitarDiagramsJS } from '../../../guitar-diagrams.js';
+import { GuitarDiagramsJS } from '../../../src/guitar-diagrams.mjs';
 
 // ========== BEGIN testing
 let gdjTesting = new GuitarDiagramsJS();