Merge pull request #2 from ourchitecture/our-dev

chore: use ourstage references

.github/CONTRIBUTING.md

@@ -3,3 +3,14 @@
 [![GitHub Repo stars](https://img.shields.io/github/stars/ourchitecture/monorepo)](https://github.com/ourchitecture/monorepo)
 
 Welcome one and all. This project is very early in development and will update contributor guidelines in the near future. Please [star this repository](https://github.com/ourchitecture/monorepo) and check back regularly for updates.
+
+## Prerequisites
+
+1. A docker-compatible CLI, like Rancher Desktop, Podman Desktop with a `docker` alias, or Docker Desktop (free for open source and small organizations, but requires a paid license for larger organizations).
+2. The Long-Term Support version of NodeJS.
+
+## Getting started
+
+1. First, [setup the Nexus server](../src/systems/dev/nexus/README.md)
+2. Once Nexus is configured and running and `yarn` has authenticated to the server
+3. Navigate to the root of this repository and run `make` to install and check all projects in the monorepo.

.gitignore

@@ -118,3 +118,9 @@ $RECYCLE.BIN/
 # Specific directories.
 **/.wireit/
 **/node_modules/
+
+# Wildcard files.
+.env*
+*.env
+*.bak
+*.log

.hintrc

@@ -0,0 +1,11 @@
+{
+    "extends": ["development"],
+    "hints": {
+        "compat-api/html": [
+            "default",
+            {
+                "ignore": ["meta[name=theme-color]"]
+            }
+        ]
+    }
+}

.markdownlint-cli2.yaml

@@ -5,8 +5,8 @@ ignores:
     - '**/.husky/**'
     - '**/.vscode/**'
     - '**/.wireit/**'
+    - '**/src/systems/dev/backstage/ourstage/**'
     - '**/node_modules/**'
-    - 'src/systems/dev/backstage/**'
 config:
     # Spaces after list markers.
     MD030:

.prettierignore

@@ -5,11 +5,14 @@
 # Specific directories.
 **/.changeset
 **/.husky
+**/.vscode
 **/.wireit
 **/.yarn/releases
+**/src/systems/dev/backstage/ourstage
 
 # File patterns.
 **/*.drawio
+**/*.log
 **/*.md
 **/*.png
 **/*.svg
@@ -18,5 +21,3 @@
 **/.yarnrc.yaml
 **/LICENSE
 **/yarn.lock
-
-src/systems/dev/backstage/

.prettierrc.yaml

@@ -1,3 +1,7 @@
+overrides:
+    - files: ['*.json', '.hintrc']
+      options:
+          trailingComma: none
 printWidth: 80
 semi: false
 singleQuote: true

.yarnrc.yml

@@ -1,7 +1,15 @@
+compressionLevel: mixed
+
+enableGlobalCache: true
+
+# Do not track.
 enableTelemetry: false
 
+# Only hoist dependencies at the workspace level.
 nmHoistingLimits: workspaces
 
+# Use classic npm link behavior.
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-remote.cjs
+# Path to the pinned version of yarn.
+yarnPath: .yarn/releases/yarn-4.1.1.cjs

README.md

@@ -4,7 +4,9 @@
 
 ## Projects
 
-- [leadof.me](./src/projects/leadof/me/)
+- Local package caching with [Nexus server](./src/systems/dev/nexus/README.md). _\*Note that dependencies for this project are configured to install through this package registry._
+- [Backstage development portal](./src/systems/dev/backstage/ourstage/README.md).
+- [leadof.me](./src/systems/leadof/me/README.md) website.
 
 ## Contributing
 

makefile

@@ -1,33 +1,129 @@
 .DEFAULT_GOAL:=all
 
-all: init install check
+all: install-dependencies install check
 
-.PHONY: init
-init:
-	@echo "Initializing monorepo..."
+.PHONY: install-dependencies
+install-dependencies:
+	@echo "Installing monorepo dependencies..."
 	@yarn install --immutable
 	@yarn workspaces foreach --all --interlaced run install --immutable
-	@echo "Successfully initialized monorepo."
+	@echo "Successfully installed monorepo dependencies."
 
-	@echo "Initializing independent projects..."
+	@echo "Installing independent project dependencies..."
 	@cd ./src/systems/dev/backstage/ourstage && make $@
-	@echo "Successfully initialized independent projects."
+	@echo "Successfully installed independent project dependencies."
+.PHONY: init
+init: install-dependencies
 
 .PHONY: install
 install:
 	@echo "Installing independent projects..."
 	@cd ./src/systems/dev/backstage/ourstage && make $@
 	@echo "Successfully installed independent projects."
 
-.PHONY: check
-check:
-	@echo "Checking monorepo..."
+# BUG: No solution found.
+# See similar issue: https://github.com/yarnpkg/berry/issues/4117
+# .PHONY: check-audit
+# check-audit:
+# 	@echo "Auditing monorepo..."
+# 	@yarn npm audit --all
+# 	@echo "Successfully audited monorepo."
+
+# 	@echo "Auditing independent projects..."
+# 	@cd ./src/systems/dev/backstage/ourstage && make $@
+# 	@echo "Successfully audited independent projects."
+# .PHONY: audit
+# audit: check-audit
+
+.PHONY: check-lint
+check-lint:
+	@echo "Linting monorepo..."
 	@yarn workspaces foreach --all --interlaced run lint
-	@echo "Successfully checked monorepo."
+	@echo "Successfully linted monorepo."
+
+	@echo "Linting independent projects..."
+	@cd ./src/systems/dev/backstage/ourstage && make $@
+	@echo "Successfully linted independent projects."
+.PHONY: lint
+lint: check-lint
 
-	@echo "Checking independent projects..."
+.PHONY: check-test
+check-test:
+	@echo "Testing monorepo..."
+	@yarn workspaces foreach --all --interlaced run test
+	@echo "Successfully tested monorepo."
+
+	@echo "Testing independent projects..."
+	@cd ./src/systems/dev/backstage/ourstage && make $@
+	@echo "Successfully tested independent projects."
+.PHONY: test
+test: check-test
+
+.PHONY: check
+check: check-lint check-test
+
+.PHONY: format
+format:
+	@echo "Formatting monorepo..."
+	@yarn workspaces foreach --all --interlaced run format
+	@echo "Successfully formatted monorepo."
+
+.PHONY: up
+up:
+	@echo "Starting the system..."
+	@cd ./src/systems/dev/backstage/ourstage && make $@
+	@echo "Successfully started the system."
+.PHONY: start
+start: up
+.PHONY: startup
+startup: up
+.PHONY: serve
+serve: up
+.PHONY: run
+run: up
+
+.PHONY: down
+down:
+	@echo "Stopping the system..."
+	@cd ./src/systems/dev/backstage/ourstage && make $@
+	@echo "Stopping started the system."
+.PHONY: stop
+stop: down
+.PHONY: shutdown
+shutdown: down
+
+.PHONY: upgrade
+upgrade:
+	@echo "Upgrading monorepo..."
+	@yarn upgrade-interactive --latest
+	@echo "Successfully upgraded monorepo."
+
+	@echo "Upgrading independent projects..."
+	@cd ./src/systems/dev/backstage/ourstage && make $@
+	@echo "Successfully upgraded independent projects."
+
+.PHONY: clean
+clean:
+	@echo "Cleaning monorepo..."
+	@echo "Successfully cleaned monorepo."
+
+	@echo "Cleaning independent projects..."
+	@cd ./src/systems/dev/backstage/ourstage && make $@
+	@echo "Successfully cleaned independent projects."
+
+.PHONY: reset
+reset: clean
+	@echo "Resetting monorepo..."
+	@rm --recursive --force \
+		./.wireit/ \
+		./.yarn/cache \
+		./.yarn/install-state.gz \
+		./node_modules
+	@echo "Successfully reset monorepo."
+
+	@echo "Resetting independent projects..."
 	@cd ./src/systems/dev/backstage/ourstage && make $@
-	@echo "Successfully checked independent projects."
+	@echo "Successfully reset independent projects."
 
 ################################################################################
 # Git convience commands

package.json

@@ -18,19 +18,15 @@
     "engines": {
         "node": ">=20.11.1 <21.0.0",
         "npm": ">=10.4.0",
-        "yarn": ">=1.22.21"
+        "yarn": ">=1.22.19"
     },
     "homepage": "https://github.com/ourchitecture/monorepo/",
     "license": "MIT OR CC0-1.0",
     "main": "",
     "name": "@ourchitecture/monorepo",
-    "packageManager": "yarn@4.1.0",
+    "packageManager": "yarn@4.1.1",
     "private": true,
     "repository": "https://github.com/ourchitecture/monorepo/",
-    "resolutions": {
-        "@types/react": "^18",
-        "@types/react-dom": "^18"
-    },
     "scripts": {
         "build:ourstage": "wireit",
         "format": "prettier --write .",

src/docs/techdocs/README.md

@@ -0,0 +1,5 @@
+# Ourchitecture Monorepo
+
+Coming soon...
+
+[Maintenance](./maintenance.md)

src/docs/techdocs/maintenance.md

@@ -0,0 +1,43 @@
+# Maintenance
+
+- Perform an interactive and assisted upgrade using `make upgrade`.
+- Review all "Containerfile" image references.
+- Review the below...
+
+## NodeJS projects
+
+Check ".node-version" against the current NodeJS LTS version.
+
+The "packageManager" entry for "packages.json" should usually be set to the latest release of the specific package manager being used by the project.
+
+Generally, the "engines" section of "packages.json" should be set to:
+
+- "node" should be greater than or equal to the current Long-Term Support (LTS) version to ensure all machines are using LTS or later and less than the next major version beyond the current LTS version to ensure that LTS minor upgrades and patches are automatically included until the version can be bumped. The version range should not include "Current" releases that are not yet under LTS.
+- "npm" should be greater than or equal to the version shipped with the most recent Long-Term Support (LTS) version specified in the "node" version range. This allows the primary "node" depenendency to be upgraded to include any version of "npm" greater than the version specified.
+- "yarn" should be greater than or equal to the version shipped with the most recent Long-Term Support (LTS) version in the most recent "node" OCI container image. While "node" is dependent on NodeJS releases and "npm" is dependent on bundling with "node", the "yarn" version specifically depends on the container release.
+
+### Example
+
+```json
+{
+  "engines": {
+    /*
+      A version range where the lower version is the most recent LST version
+      relative to the last time project maintainers checked it. The second
+      version would be the next major upgrade to allow the LTS version to
+      automatically be included when minor upgrades and patches are released.
+    */
+    "node": ">=20.11.1 <21.0.0",
+    /*
+      This is the version shipped inside of the most recent OCI container
+      image associated with the LTS version of "node" above.
+    */
+    "npm": ">=10.4.0",
+    /*
+      This is the version shipped inside of the most recent OCI container
+      image associated with the LTS version of "node" above.
+    */
+    "yarn": ">=1.22.19"
+  }
+}
+```

src/systems/dev/backstage/catalog/catalog-info.yaml

@@ -0,0 +1,13 @@
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-location
+apiVersion: backstage.io/v1alpha1
+kind: Location
+metadata:
+    name: ourchitecture-catalog
+    description: The Ourchitecture entities catalog
+    annotations:
+        github.com/project-slug: ourchitecture/monorepo
+        backstage.io/source-location: url:https://github.com/ourchitecture/monorepo/
+spec:
+    targets:
+        - ./groups/catalog-info.yaml
+        - ./users/catalog-info.yaml

src/systems/dev/backstage/catalog/groups/catalog-info.yaml

@@ -0,0 +1,18 @@
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group
+apiVersion: backstage.io/v1alpha1
+kind: Group
+metadata:
+    description: The Ourchitecture team
+    name: ourchitecture
+    links:
+        - title: Ourchitecture.io
+          url: http://ourchitecture.io
+        - icon: github
+          title: Ourchitecture @GitHub
+          url: http://github.com/ourchitectureio
+spec:
+    children: []
+    profile:
+        displayName: Ourchitecture Team
+        picture: https://avatars.githubusercontent.com/u/97544811?v=4
+    type: team

src/systems/dev/backstage/catalog/users/catalog-info.yaml

@@ -0,0 +1,34 @@
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-user
+apiVersion: backstage.io/v1alpha1
+kind: User
+metadata:
+    name: ourchitectureio
+    links:
+        - icon: github
+          title: GitHub
+          url: https://github.com/ourchitectureio
+        - icon: twitter
+          title: Twitter
+          url: https://twitter.com/ourchitectureio
+spec:
+    profile:
+        displayName: Ourchitecture Automation
+        picture: https://avatars.githubusercontent.com/u/97544811?v=4
+    memberOf: [ourchitecture]
+---
+apiVersion: backstage.io/v1alpha1
+kind: User
+metadata:
+    name: ericis
+    links:
+        - icon: github
+          title: GitHub
+          url: https://github.com/ericis
+        - icon: linkedin
+          title: LinkedIn
+          url: https://linkedin.com/in/iseric
+spec:
+    profile:
+        displayName: Eric Swanson
+        picture: https://media.licdn.com/dms/image/C4E03AQHRTsy5SALJPw/profile-displayphoto-shrink_800_800/0/1552059989146?e=1715817600&v=beta&t=kLFz3GWAGL2AML5w_i-UL96usjx57PODB9lpJZ1CowY
+    memberOf: [ourchitecture]