Resolving feedback on @minecraft/math after testing internally (#4)

Switch to a couple of classes with static methods to remove ambiguity with shortly named methods. Add a release pipeline to do build validations for now, but not the actual release.

Author: rlandav

.github/workflows/release-changes.yml

@@ -0,0 +1,36 @@
+name: Release Changes
+
+environment: release
+
+on: 
+  push:
+    branches:
+      - main
+
+runs-on: ubuntu-latest
+
+steps:
+  - uses: actions/checkout@v4
+    with:
+      persist-credentials: false
+  - name: Use Node.js 20.x
+    uses: actions/setup-node@v3
+    with:
+      node-version: '20.x'
+  - run: npm ci
+  - run: npm run test # Fully build the repo so we have artifacts available to create releases, include tests so we don't ship in a broken state
+  
+  # Uncomment the below when ready to publish to NPM for the first time
+  # - name: Set git credentials
+  #   run: |
+  #     git config --global user.name "Raphael Landaverde"
+  #     git config --global user.email "[email protected]"
+  #     git remote set-url origin "https://[email protected]/mojang/minecraft-scripting-libraries"
+  #   env:
+  #     REPO_PAT: ${{ secrets.REPO_PAT }}
+  
+  # # Pass the token on the command line for publishing
+  # - name: Publish
+  #   run: npm run release -- --token "$NPM_TOKEN" --yes --new
+  #   env:
+  #     NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

CONTRIBUTING.md

@@ -15,4 +15,8 @@ or contact [[email protected]](mailto:[email protected]) with any addi
 
 ## Specific Guidelines
 
-Contributions to these libraries are welcome! These libraries are maintained by Mojang but we are open to contributions and bug fixes. In general, we consider the backwards compatibility and versioning to be the absolute top priority when making changes to the libraries. Because of this, we strictly adhere to semver for changes, and libraries depend on minecraft modules at specific major versions as well. Any PR submitted to any library **must** contain a change file using the beachball tool to indicate the severity of the change. When a change is submitted, it will automatically update versions and publish to NPM via our pipelines.
+Contributions to these libraries are welcome! These libraries are maintained by Mojang but we are open to contributions and bug fixes. In general, we consider the backwards compatibility and versioning to be the absolute top priority when making changes to the libraries. Because of this, we strictly adhere to semver for changes, and libraries depend on minecraft modules at specific major versions as well. Any PR submitted to any library **must** contain a change file using the beachball tool to indicate the severity of the change. When a change is submitted, it will automatically update versions and publish to NPM via our pipelines.
+
+### Naming
+
+We generally follow the naming conventiosn specified by the [google style guide](https://google.github.io/styleguide/jsguide.html#naming). There is other general good practice within the style guide as well, though generally the vast majority of our style is enforced via a combination of ESLint and prettier enforcement at PR time.

change/@minecraft-math-d8edc841-cbdc-48e2-adc6-f1d7c02b8571.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "Switch to a couple of classes with static methods to remove ambiguity with shortly named methods",
+  "packageName": "@minecraft/math",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/eslint-plugin-minecraft-linting-672bc1dd-52b6-4cc8-a04f-26811ec7f717.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Start from a 0 version so it bumps to a 1.0.0 version",
+  "packageName": "eslint-plugin-minecraft-linting",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

libraries/math/README.md

@@ -4,21 +4,21 @@ A set of utilities and functions for common math operations. Major pieces are co
 
 ## Vector3
 
-A set of free functions and a wrapper class for common vector3 operations. Two distinct patterns are supported, a more pure computational approach operating on the Vector3 interface with no mutation, and a separate wrapper object oriented approach following a "builder" pattern. It is mostly preference whether you prefer the more "mutation" heavy pattern or the functional pattern, so it depends on the structure of your code. Under the covers, the same helpers are used.
+A set of utility functions and a wrapper class for common vector3 operations. Two distinct patterns are supported, a more pure computational approach operating on the Vector3 interface with no mutation, and a separate wrapper object oriented approach following a "builder" pattern. It is mostly preference whether you prefer the more "mutation" heavy pattern or the functional pattern, it depends on the structure of your code. Under the covers, the same helpers are used.
 
 ### Pure Functional Style
 
 ```ts
 import { Vector3, world } from '@minecraft/server';
 import { MinecraftDimensionTypes } from '@minecraft/vanilla-data';
-import { add, subtract, cross } from '@minecraft/math';
+import { Vector3Utils } from '@minecraft/math';
 
 const vectorA: Vector3 = {x: 1, y: 2, z:3};
 const vectorB: Vector3 = {x: 4, y: 5, z:6};
 
-const resultAdd = add(vectorA, vectorB); // {x:5, y:7, z:9}
-const resultSubtract = subtract(vectorA, vectorB); // {x:-3, y:-3, z:-3}
-const resultAdd = cross(vectorA, vectorB); // {x:-3, y:6, z:-3}
+const resultAdd = Vector3Utils.add(vectorA, vectorB); // {x:5, y:7, z:9}
+const resultSubtract = Vector3Utils.subtract(vectorA, vectorB); // {x:-3, y:-3, z:-3}
+const resultAdd = Vector3Utils.cross(vectorA, vectorB); // {x:-3, y:6, z:-3}
 
 console.log(toString(vectorA)); // Prints out "1, 2, 3"
 
@@ -53,4 +53,4 @@ dimension.spawnParticle("minecraft:colored_flame_particle", vectorA);
 @minecraft/math is published to NPM and follows standard semver semantics. To use it in your project, there are two main options:
 
 1. Download `@minecraft/math` from NPM by doing `npm install @minecraft/math` within your scripts pack. By using `@minecraft/math`, you will need to do some sort of bundling to merge the library into your packs code. We recommend using [esbuild](https://esbuild.github.io/getting-started/#your-first-bundle) for simplicity.
-2. This repository publishes releases for `@minecraft/math`, and on each release we attach a pre-bundled copy of the `@minecraft/math` module. Feel free to take this JS bundle and integrate into your projects as it contains all dependencies coupled together, and this pattern does not require bundling.
+2. This repository publishes releases for `@minecraft/math`, and on each release we attach a pre-bundled copy of the `@minecraft/math` module. Feel free to take this JS bundle and integrate into your projects as it contains all dependencies coupled together, and this pattern does not require bundling within your own project.

libraries/math/api-report/math.api.md

@@ -4,95 +4,70 @@
 
 ```ts
 
-import { Vector2 } from '@minecraft/server';
-import { Vector3 } from '@minecraft/server';
+import type { Vector2 } from '@minecraft/server';
+import type { Vector3 } from '@minecraft/server';
 
 // @public
-export function add(v1: Vector3, v2: Vector3): Vector3;
+export function clampNumber(val: number, min: number, max: number): number;
 
 // @public
-export const back: Vector3;
-
-// @public
-export function clamp(v: Vector3, limits?: {
-    min?: Partial<Vector3>;
-    max?: Partial<Vector3>;
-}): Vector3;
-
-// @public
-export function clamp_number(val: number, min: number, max: number): number;
-
-// @public
-export function cross(a: Vector3, b: Vector3): Vector3;
-
-// @public
-export function dot(a: Vector3, b: Vector3): number;
-
-// @public
-export const down: Vector3;
-
-// @public
-export const east: Vector3;
-
-// @public
-export function equals(v1: Vector3, v2: Vector3): boolean;
-
-// @public
-export function floor(v: Vector3): Vector3;
+export class Vector2Builder implements Vector2 {
+    constructor(vec: Vector2, arg?: never);
+    constructor(x: number, y: number);
+    // (undocumented)
+    toString(options?: {
+        decimals?: number;
+        delimiter?: string;
+    }): string;
+    // (undocumented)
+    x: number;
+    // (undocumented)
+    y: number;
+}
 
 // @public
-export const forward: Vector3;
+export class Vector2Utils {
+    static toString(v: Vector2, options?: {
+        decimals?: number;
+        delimiter?: string;
+    }): string;
+}
 
 // @public
-export const left: Vector3;
+export const VECTOR3_BACK: Vector3;
 
 // @public
-export function magnitude(v: Vector3): number;
+export const VECTOR3_DOWN: Vector3;
 
 // @public
-export function normalize(v: Vector3): Vector3;
+export const VECTOR3_EAST: Vector3;
 
 // @public
-export const north: Vector3;
+export const VECTOR3_FORWARD: Vector3;
 
 // @public
-export const one: Vector3;
+export const VECTOR3_LEFT: Vector3;
 
 // @public
-export const right: Vector3;
+export const VECTOR3_NORTH: Vector3;
 
 // @public
-export function scale(v1: Vector3, scale: number): Vector3;
+export const VECTOR3_ONE: Vector3;
 
 // @public
-export const south: Vector3;
+export const VECTOR3_RIGHT: Vector3;
 
 // @public
-export function subtract(v1: Vector3, v2: Vector3): Vector3;
+export const VECTOR3_SOUTH: Vector3;
 
 // @public
-export const up: Vector3;
+export const VECTOR3_UP: Vector3;
 
 // @public
-export class Vector2Builder implements Vector2 {
-    constructor(vec: Vector2, arg?: never);
-    constructor(x: number, y: number);
-    // (undocumented)
-    toString(options?: {
-        decimals?: number;
-        delimiter?: string;
-    }): string;
-    // (undocumented)
-    x: number;
-    // (undocumented)
-    y: number;
-}
+export const VECTOR3_WEST: Vector3;
 
 // @public
-export function vector2ToString(v: Vector2, options?: {
-    decimals?: number;
-    delimiter?: string;
-}): string;
+export const VECTOR3_ZERO: Vector3;
 
 // @public
 export class Vector3Builder implements Vector3 {
@@ -125,16 +100,25 @@ export class Vector3Builder implements Vector3 {
 }
 
 // @public
-export function vector3ToString(v: Vector3, options?: {
-    decimals?: number;
-    delimiter?: string;
-}): string;
-
-// @public
-export const west: Vector3;
-
-// @public
-export const zero: Vector3;
+export class Vector3Utils {
+    static add(v1: Vector3, v2: Vector3): Vector3;
+    static clamp(v: Vector3, limits?: {
+        min?: Partial<Vector3>;
+        max?: Partial<Vector3>;
+    }): Vector3;
+    static cross(a: Vector3, b: Vector3): Vector3;
+    static dot(a: Vector3, b: Vector3): number;
+    static equals(v1: Vector3, v2: Vector3): boolean;
+    static floor(v: Vector3): Vector3;
+    static magnitude(v: Vector3): number;
+    static normalize(v: Vector3): Vector3;
+    static scale(v1: Vector3, scale: number): Vector3;
+    static subtract(v1: Vector3, v2: Vector3): Vector3;
+    static toString(v: Vector3, options?: {
+        decimals?: number;
+        delimiter?: string;
+    }): string;
+}
 
 // (No @packageDocumentation comment for this package)
 

libraries/math/src/general/clamp.ts

@@ -5,6 +5,6 @@
  *
  * @public
  */
-export function clamp_number(val: number, min: number, max: number): number {
+export function clampNumber(val: number, min: number, max: number): number {
     return Math.min(Math.max(val, min), max);
 }