From e05527fa8da4a46a03dd1ac783b1826e3bfcfaf4 Mon Sep 17 00:00:00 2001 From: Zaran Lalvani Date: Tue, 30 Apr 2024 00:24:37 -0400 Subject: [PATCH] chore: readme changes (#58) --- .github/workflows/publish-cli-on-merge.yml | 1 + README.md | 43 ++++++++++++---------- apps/cli/README.md | 3 -- apps/cli/package.json | 2 +- 4 files changed, 26 insertions(+), 23 deletions(-) delete mode 100644 apps/cli/README.md diff --git a/.github/workflows/publish-cli-on-merge.yml b/.github/workflows/publish-cli-on-merge.yml index c305f0e..60f7b55 100644 --- a/.github/workflows/publish-cli-on-merge.yml +++ b/.github/workflows/publish-cli-on-merge.yml @@ -56,6 +56,7 @@ jobs: - run: pnpm install --frozen-lockfile - run: pnpm --filter=bumpgen run build + - run: cp README.md apps/cli/README.md # copy the README to the CLI folder so it gets published - run: pnpm --filter=bumpgen publish --tag latest --access public --no-git-checks env: NODE_AUTH_TOKEN: "${{ secrets.NPM_TOKEN }}" diff --git a/README.md b/README.md index fdfa877..9399846 100644 --- a/README.md +++ b/README.md @@ -18,31 +18,33 @@

## 📝 Summary -`bumpgen` bumps your dependencies and makes code changes for you if anything breaks. -This may be a common scenario: +`bumpgen` bumps your **TypeScript / TSX** dependencies and makes code changes for you if anything breaks. -> you: "I should upgrade to the latest version of x, it has banging new features and impressive performance improvments" +![demo]() + +Here's a common scenario: + +> you: "I should upgrade to the latest version of x, it has banging new features and impressive performance improvements" > -> you (internal monologue): _I don't want to feel pain anymore_ +> you (5 minutes later): _nevermind, that broke a bunch of stuff_ Then use `bumpgen`! **How does it work?** -- It uses [ts-morph](https://github.com/dsherret/ts-morph) to turn your codebase into an AST to understand code relationships -- Uses the AST to get type definitions for external methods to understand how to use new package versions -- Creates a plan graph DAG to execute things in the correct order to get to the root of problems (ref: [arxiv 2309.12499](https://huggingface.co/papers/2309.12499)) - -![demo](https://s3.amazonaws.com/static.xeol.io/mkdirp-demo-optimized.gif) +- `bumpgen` builds your project to understand what broke when a dependency was bumped +- Then `bumpgen` uses [ts-morph](https://github.com/dsherret/ts-morph) to create an _abstract syntax tree_ from your code, to understand the relationships between statements +- It also uses the AST to get type definitions for external methods to understand how to use new package versions +- `bumpgen` then creates a _plan graph_ DAG to execute things in the correct order to handle propagating changes (ref: [arxiv 2309.12499](https://huggingface.co/papers/2309.12499)) -> `bumpgen` only supports typescript or tsx at the moment, but we're working on adding support for other strongly typed languages like C#, Java and Go +> `bumpgen` only supports typescript and tsx at the moment, but we're working on adding support for other strongly typed languages like C#, Java and Go ## 🚀 Get Started -To get started, you'll need an OpenAI API key. `gpt-4-turbo-preview` from OpenAI is the only supported model at this time. +To get started, you'll need an OpenAI API key. `gpt-4-turbo-preview` from OpenAI is the only supported model at this time, though we plan on supporting more soon. -Then, run `bumpgen` this: +Then, run `bumpgen`: ``` > export LLM_API_KEY="" @@ -53,16 +55,20 @@ Then, run `bumpgen` this: where `@tanstack/react-query` is the package you want to bump and `5.28.14` is the version you want to bump to. -> If you'd like to be first to try the `bumpgen` GitHub App to replace your usage of dependabot + renovatebot, sign up [here](https://www.xeol.io/beta) +You can also run `bumpgen` without arguments and select which package to upgrade from the menu. Use `bumpgen --help` for a complete list of options. + +> If you'd like to be first in line to try the `bumpgen` GitHub App to replace your usage of dependabot + renovatebot, sign up [here](https://www.xeol.io/beta) ## Limitations There are some limitations you should know about. -- `bumpgen` can't handle multiple packages at this time. It will fail to upgrade packages that require peer dependencies to be updated the same time to work such as `@octokit/core` and `@octokit/plugin-retry`. +- `bumpgen` relies on build errors to determine what needs to be fixed. If an issue is caused by a behavioral change, `bumpgen` won't detect it. +- `bumpgen` can't handle multiple packages at the same time. It will fail to upgrade packages that require peer dependencies to be updated the same time to work such as `@octokit/core` and `@octokit/plugin-retry`. - `bumpgen` is not good with very large frameworks like `vue`. These kind of upgrades (and vue 2 -> 3 specifically) can be arduous even for a human. ## 🏙️ Architecture + ``` > bumpgen @tanstack/react-query 5.28.14 │ @@ -111,15 +117,15 @@ There are some limitations you should know about. #### Abstract Syntax Tree -The AST is generated from **[ts-morph](https://github.com/dsherret/ts-morph)**. This AST allows `bumpgen` to understand the relationship between code properties in a codebase. +The AST is generated from **[ts-morph](https://github.com/dsherret/ts-morph)**. This AST allows `bumpgen` to understand the relationship between nodes in a codebase. #### Plan Graph -The plan graph is a concept detailed in **[codeplan](https://huggingface.co/papers/2309.12499)** by Microsoft. The plan graph allows `bumpgen` to not only fix an issue at a point but also fix the 2nd order breaking changes from the fix itself. In short, it allows `bumpgen` to perpetuate a fix to the rest of the codebase. +The plan graph is a concept detailed in **[codeplan](https://huggingface.co/papers/2309.12499)** by Microsoft. The plan graph allows `bumpgen` to not only fix an issue at a point but also fix the 2nd order breaking changes from the fix itself. In short, it allows `bumpgen` to propagate a fix to the rest of the codebase. #### Prompt Context -We pass the plan graph, the error, and the actual file with the breaking change as context to the LLM to maximize it's ability to fix the issue. +We pass the plan graph, the error, and the actual file with the breaking change as context to the LLM to maximize its ability to fix the issue. #### LLM @@ -129,7 +135,6 @@ We only support `gpt-4-turbo-preview` at this time. meme

- ## ⏱️ Benchmark ``` @@ -153,4 +158,4 @@ Contributions are welcome! To get set up for development, see [Development](./.g - [ ] Java support - [ ] Go support -[Join](https://img.shields.io/discord/1233126412785815613) our Discord community to contribute, learn more, and ask questions! +[Join](https://discord.gg/J7E9BqVHkG) our Discord community to contribute, learn more, and ask questions! diff --git a/apps/cli/README.md b/apps/cli/README.md deleted file mode 100644 index c2e0ac7..0000000 --- a/apps/cli/README.md +++ /dev/null @@ -1,3 +0,0 @@ -## Getting Started - -TODO \ No newline at end of file diff --git a/apps/cli/package.json b/apps/cli/package.json index a8217509..b9b3839 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -1,6 +1,6 @@ { "name": "bumpgen", - "version": "0.1.2", + "version": "0.1.3", "scripts": { "build": "tsup src/index.tsx --format esm", "dev": "tsup src/index.tsx --format esm --watch",