Add developer guide

DEVELOPER.md

@@ -0,0 +1,85 @@
+# Developer Guide
+
+## Package scripts
+
+This workspace contains the following top-level npm scripts:
+
+- `ci`: Run tests across the the whole repository and build all public packages
+- `lint`: Lint the source code across the whole repository
+- `test`: Run tests across the whole repository (or use `test:watch` to enable watch mode)
+- `verify`: Lint and run tests across the whole repository
+- `coverage`: Generate a test coverage report across the whole repository
+- `build`: Build all public packages
+- `clean`: Clean all build artifacts
+- `version`: Retrieve the public package version (according to the source code within the repository)
+- `publish`: Publish all public packages to npm
+
+## Common tasks
+
+### Adding dependencies
+
+This repository uses pnpm's [Workspaces](https://pnpm.io/workspace) feature to manage internal dependencies between packages.
+
+To add dependencies within a package, use one of the following methods:
+
+- Edit the relevant package's `package.json`, then run `pnpm install` anywhere within the repository
+- `cd` into the relevant package, then run `pnpm add <dependency>` to install the dependency
+- run `pnpm add --filter <package> <dependency>`  anywhere within the repository
+
+See `pnpm add --help` and the [pnpm workspaces documentation](https://pnpm.io/workspace) for more details.
+
+## Code style
+
+This workspace uses Prettier for code formatting, with rules enforced via ESLint.
+
+## Workflow
+
+This project uses Github pull requests (PRs) for merging code, and Github Actions for continuous integration (CI).
+
+### Git branch strategy
+
+This repository contains the following long-lived branches:
+
+- `main`: Branch containing the most recently published version
+- `develop`: Stable development branch containing the upcoming 'next' release
+
+Points to note:
+
+- Branch protection rules and CI tests are in place for both these branches to prevent accidentally committing broken code changes
+- Features not yet ready for release remain on short-lived feature branches until they are ready to be merged into the `develop` branch
+- Packages are automatically published by CI whenever a PR is successfully merged into the `main` branch
+
+### Development workflow
+
+Changes are merged to the repository as follows:
+
+1. Create a new feature branch from the current `develop` branch, named with the relevant prefix:
+    - `feature/...` - Branch contains new features
+    - `fix/...` - Branch contains bugfixes
+    - `docs/...` - Branch contains documentation updates
+    - `chore/...` - Branch contains routine admin tasks
+    > _Note that a `wip/...` prefix indicates a branch that is not intended to be merged_
+2. Commit code changes to the feature branch
+3. Rebase on the latest `develop` branch to incorporate upstream changes
+4. Raise a PR that targets `develop` as its base branch (note that this is **not** the default repository branch)
+5. Wait for CI tests to pass
+6. Merge the PR using the 'rebase' merge stragegy
+
+### Releasing
+
+When the contents of the `develop` branch are ready to be released, follow these steps to publish a new version:
+
+1. Create a new branch from the current `develop` branch, named with the `release/...` prefix
+2. Add a single commit that updates the relevant `package.json` version numbers
+3. Raise a PR that targets `develop` as its base branch (note that this is **not** the default repository branch)
+4. Wait for CI tests to pass
+5. Merge the PR using the 'rebase' merge stragegy
+6. Raise a new PR that merges `develop` into `main`
+2. Wait for CI tests to pass
+3. Merge the PR using the 'rebase' merge stragegy
+
+This will cause CI to perform the following actions:
+
+- Build and publish all public packages
+- Tag the repository with the current package version
+- Create a Github 'Release' page linked to the release commit

README.md

@@ -0,0 +1,46 @@
+# AG Grid Developer Tools
+
+This repository contains a selection of developer tools related to [AG Grid](https://github.com/ag-grid/ag-grid) development.
+
+## Repository layout
+
+This repository is organised as a monorepo containing various packages.
+
+The following packages contain user-facing tools:
+
+- [`cli`](./packages/cli/): AG Grid developer toolkit
+- [`codemods`](./packages/codemods/): AG Grid codemods (bundled with the AG Grid developer toolkit)
+
+The following packages contain internal library helpers:
+
+- [`ast`](./packages/ast/): AST transformation tools
+- [`codemod-utils`](./packages/codemod-utils/): Codemod utility helpers
+- [`systemjs-plugin`](./packages/systemjs-plugin/): SystemJS plugin for TypeScript/JSX/CSS source files
+- [`test-utils`](./packages/test-utils/): Automated testing helpers
+- [`types`](./packages/types/): Shared type definitions
+
+The following packages contain configuration shared across multiple internal packages:
+
+- [`build-config`](./packages/build-config/): Build tool configuration
+- [`build-tools`](./packages/build-tools/): Custom build tools
+
+## Developing
+
+### Installation
+
+This repository uses [pnpm](https://pnpm.io/) to manage its dependencies. This can be installed via the Node.js built-in [corepack](https://nodejs.org/api/corepack.html) system as follows:
+
+```
+corepack enable
+corepack prepare pnpm@latest --activate
+```
+
+Once installed, run the following command to install the project dependencies:
+
+```
+pnpm install
+```
+
+### Contributing
+
+See the [Developer Guide](./DEVELOPER.md) for more details.

packages/cli/README.md

@@ -0,0 +1,23 @@
+# @ag-grid-community/cli
+
+> _AG Grid developer toolkit_
+
+The AG Grid developer toolkit is distributed as a command-line tool that assists with tasks such as migrating a codebase to a newer version of AG Grid.
+
+## Usage
+
+Run the following command to list available commands:
+
+```
+npx @ag-grid-community/cli --help
+```
+
+> _Note that it is recommended to run a specific version of the developer toolkit, e.g._ `@ag-grid-community/[email protected]`
+
+### Available commands
+
+The CLI tool contains the following commands:
+
+- `migrate`: Migrate an existing codebase to use a newer version of AG grid
+
+See the command-line help for more details.

packages/cli/package.json

@@ -16,8 +16,9 @@
   "type": "module",
   "main": "./index.ts",
   "scripts": {
-    "build": "pnpm run build:lib && pnpm run build:codemods && pnpm run build:pkg",
+    "build": "pnpm run build:lib && pnpm run build:codemods && pnpm run build:readme && pnpm run build:pkg",
     "build:lib": "vite build",
+    "build:readme": "cp README.md dist/README.md",
     "build:pkg": "pnpm run --filter build-tools pkg $PWD $PWD/dist/package.json",
     "build:codemods": "pnpm run build:codemods:lib && pnpm run build:codemods:pkg",
     "build:codemods:lib": "vite build --config codemods.vite.config.js",

packages/codemods/DEVELOPER.md

@@ -0,0 +1,72 @@
+# Developer Guide
+
+## Package scripts
+
+This package contains the following npm scripts:
+
+- `build`: Build this package (outputs the compiled package into the `./dist` directory)
+- `lint`: Lint the source code
+- `test`: Run tests (or use `test:watch` to enable watch mode)
+- `build:tasks`: Build dependencies for the task runner scripts (see below)
+
+## Common tasks
+
+> These tasks assume the task runner script dependencies have already been built via `pnpm run build:tasks`
+
+### Creating a new codemod
+
+All codemods are tied to a specific release version. To create a new codemod release, run the following command within this package:
+
+```
+pnpm run task:create-version
+```
+
+This will prompt for the version number of the release, and will create the source files for the codemod based on a template.
+
+Additionally, the codemod will be referenced where necessary in source code to be exposed by the package.
+
+If you inspect the generated files, you will see that a codemod is essentially just a function that transforms an arbitrary input source file into a transformed output source file (see the [`Codemod`](../types/src/codemod.ts) type definition for the exact details).
+
+While this is very flexible, it doesn't provide much structure for transforming source code. In most cases, codemods will be performing AST transformations rather than raw text manipulations, and therefore the default codemod template creates the boilerplate for a codemod that performs a sequence of AST transformations expressed as [Babel transform plugins](https://babeljs.io/docs/plugins#transform-plugins) (see the [`AstTransform`](../types/src/transform.ts) for the exact details). The rest of these instructions assume that your codemods will be based on Babel AST transformations, however you can always transform other file formats if necessary.
+
+The newly-generated codemod version contains a `transforms.ts` file that specifies which AST transformations to apply. If you inspect this file, you will see that it does not yet specify any transforms, and will therefore not perform any code modifications when invoked.
+
+In order to modify user code, the codemod must apply one or more source code transformations.
+
+### Creating a new transform
+
+To create a new source code transformation, run the following command:
+
+```
+pnpm run task:create-transform
+```
+
+This will prompt for the name of the transform, and the version of the codemod that this transform relates to, and will create the source files for the transform based on a template.
+
+Often the codemod for a given version will perform similar tasks to codemods for previous releases. For this reason, various [plugins](./src/plugins) are provided as templates for creating new transforms from an existing pattern. The generator command will prompt whether to create the transform based on one of these plugin templates, falling back to a generic AST transform if no plugin is specified. The different plugins provide different configuration options, so see the plugin source code for usage instructions.
+
+Note that the newly-created transform is a Babel transform plugin - see Babel's [Plugin Development documentation](https://babeljs.io/docs/plugins#plugin-development) for more details on how to write plugins.
+
+If you chose to add this transform to a codemod version when prompted generator command, the transform will be exposed in that codemod version's `transforms.ts` file.
+
+### Adding an existing transform to a codemod version
+
+To add a source code transformation that already exists, run the following command:
+
+```
+pnpm run task:include-transform
+```
+
+This will prompt for the name of the transform and the version of the target codemod, and will update the codemod appropriately so that it applies the transform.
+
+### Creating a new test case
+
+The easiest way to confirm that a codemod works as expected is to provide test cases that assert the expected output for a given input.
+
+To create a new test case, run the following command:
+
+```
+pnpm run task:create-test
+```
+
+This will prompt for the name of the codemod or transform that you want to test and the name of the test scenario, and will create the source files for the test scenario based on a template.

packages/codemods/README.md

@@ -0,0 +1,21 @@
+# @ag-grid-community/codemods
+
+> _AG Grid codemods_
+
+This package contains the automated source code transformations that are applied by the AG Grid developer toolkit CLI tool.
+
+The codemods are bundled along with each developer toolkit release, and can be applied with the `migrate` CLI command.
+
+## Codemod bundles
+
+Codemods are organised by release. Each codemod release typically contains a set of source transformations that can be used to migrate a user's codebase to the AG Grid version specified by that release, *from* the version specified by the immediately preceding codemod release. This means that large migrations can be performed by running multiple sequential codemod releases back-to-back.
+
+Note that a specific source transformation can be included in multiple releases: this is typically used to prepare for breaking changes during the 'deprecation' phase, then when the deprecation phase is complete and the breaking changes have happened, that specific transform will no longer be bundled for future releases.
+
+### Releases
+
+- [`31.0.0`](./src/versions/31.0.0)
+
+### Contributing
+
+See the [Developer Guide](./DEVELOPER.md) for more details.

packages/codemods/package.json

@@ -17,8 +17,9 @@
   "main": "./lib.ts",
   "module": "./lib.ts",
   "scripts": {
-    "build": "pnpm run build:lib && pnpm run build:pkg",
+    "build": "pnpm run build:lib && pnpm run build:readme && pnpm run build:pkg",
     "build:lib": "vite build",
+    "build:readme": "cp README.md dist/README.md",
     "build:pkg": "pnpm run --filter build-tools pkg $PWD $PWD/dist/package.json",
     "build:tasks": "pnpm run --filter @ag-grid-devtools/ast --filter @ag-grid-devtools/codemod-utils --filter @ag-grid-devtools/test-utils build",
     "lint": "pnpm run '/^lint:.*/'",

packages/codemods/src/plugins/transform-grid-api-methods/README.md

@@ -0,0 +1,25 @@
+# `transform-grid-api-methods`
+
+> _Transform AG Grid API Methods_
+
+## Description
+
+This plugin returns a source code transformation that will update method invocations that target AG Grid API instances.
+
+## Common tasks
+
+### Creating a new Grid API Methods transform
+
+Run the following script within the current workspace package:
+
+```
+pnpm run task:create-transform --plugin transform-grid-api-methods
+```
+
+This will prompt for the name of the transform, and will create the source files for the transform based on a template.
+
+### Adding rules to an existing Grid API Methods transform
+
+Grid API method transformation rules are typically defined in the `./replacements.ts` file within a directory that defines a Grid API Methods transform.
+
+See existing transforms for usage examples.

packages/codemods/src/plugins/transform-grid-options/README.md

@@ -0,0 +1,25 @@
+# `transform-grid-options`
+
+> _Transform AG Grid options_
+
+## Description
+
+This plugin returns a source code transformation that will update fields on AG Grid options objects, including modifying the relevant attributes on AG Grid React/Angular/Vue elements.
+
+## Common tasks
+
+### Creating a new Grid Options transform
+
+Run the following script within the current workspace package:
+
+```
+pnpm run task:create-transform --plugin transform-grid-options
+```
+
+This will prompt for the name of the transform, and will create the source files for the transform based on a template.
+
+### Adding rules to an existing Grid Options transform
+
+Grid option transformation rules are typically defined in the `./replacements.ts` file within a directory that defines a Grid Options transform.
+
+See existing transforms for usage examples.

packages/codemods/src/transforms/migrate-legacy-column-api-v31/README.md

@@ -0,0 +1,17 @@
+# `migrate-legacy-column-api-v31`
+
+> _Migrate Legacy AG Grid Column API references_
+
+## Description
+
+As of AG Grid v31.0, all AG Grid Column API methods are now exposed on the Grid API instance.
+
+This source code transformation rewrites AG Grid Column API references to target the Grid API object instead.
+
+### Add to a codemod release
+
+Add this source code transformation to a codemod release:
+
+```
+pnpm run task:include-transform --transform migrate-legacy-column-api-v31
+```

packages/codemods/src/transforms/migrate-legacy-js-grid-constructor-v31/README.md

@@ -0,0 +1,17 @@
+# `migrate-legacy-js-grid-constructor-v31`
+
+> _Migrate Legacy AG Grid constructor calls_
+
+## Description
+
+As of AG Grid v31.0, the recommended way to create vanilla JavaScript AG Grid instances is via the newly-added `createGrid()` function, rather than the legacy `new Grid()` constructor calls.
+
+This source code transformation rewrites legacy constructor calls to use the new syntax.
+
+### Add to a codemod release
+
+Add this source code transformation to a codemod release:
+
+```
+pnpm run task:include-transform --transform migrate-legacy-js-grid-constructor-v31
+```

packages/codemods/src/transforms/transform-grid-api-methods-v31/README.md

@@ -0,0 +1,25 @@
+# `transform-grid-api-methods-v31`
+
+See the [`transform-grid-api-methods`](../../plugins/transform-grid-api-methods/) plugin for usage instructions.
+
+## Common tasks
+
+### Add a new rule
+
+Replacement rules are specified in [`replacements.ts`](./replacements.ts)
+
+### Add a test case
+
+Create a new unit test scenario for this transform:
+
+```
+pnpm run task:create-test --type transform --target transform-grid-options-v31
+```
+
+### Add to a codemod release
+
+Add this source code transformation to a codemod release:
+
+```
+pnpm run task:include-transform --transform transform-grid-api-methods-v31
+```