diff --git a/.github/workflows/verify-readme-duplicated.yml b/.github/workflows/verify-readme-duplicated.yml new file mode 100644 index 0000000..f4c7877 --- /dev/null +++ b/.github/workflows/verify-readme-duplicated.yml @@ -0,0 +1,29 @@ +name: Verify Readme Duplicated + +on: + pull_request: + branches: [main] + types: [opened, synchronize] + paths: + - README.md + - apps/cli/README.md + +jobs: + check-readmes: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Verify that the readmes are the same + run: | + FILE1='README.md' + FILE2='apps/cli/README.md' + HASH1=$(sha256sum $FILE1 | awk '{print $1}') + HASH2=$(sha256sum $FILE2 | awk '{print $1}') + if [ "$HASH1" == "$HASH2" ]; then + echo "Readmes are the same." + else + echo "Repo README and CLI README are different." + exit 1 + fi 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 index c2e0ac7..9399846 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -1,3 +1,161 @@ -## Getting Started +

+ logo +

-TODO \ No newline at end of file +

+ + + + + + + + + + + + +

+ +## 📝 Summary + +`bumpgen` bumps your **TypeScript / TSX** dependencies and makes code changes for you if anything breaks. + +![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 (5 minutes later): _nevermind, that broke a bunch of stuff_ + +Then use `bumpgen`! + +**How does it work?** + +- `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 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, though we plan on supporting more soon. + +Then, run `bumpgen`: + +``` +> export LLM_API_KEY="" +> cd ~/my-repository +> npm install -g bumpgen +> bumpgen @tanstack/react-query 5.28.14 +``` + +where `@tanstack/react-query` is the package you want to bump and `5.28.14` is the version you want to bump to. + +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` 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 + │ +┌┬─────▼──────────────────────────────────────────────────────────────────────┐ +││ CLI │ +└┴─────┬──▲───────────────────────────────────────────────────────────────────┘ + │ │ +┌┬─────▼──┴───────────────────────────────────────────────────────────────────┐ +││ Core (Codeplan) │ +││ │ +││ ┌───────────────────────────────────┐ ┌──────────────────────────────────┐ │ +││ │ Plan Graph │ │ Abstract Syntax Tree │ │ +││ │ │ │ │ │ +││ │ │ │ │ │ +││ │ ┌─┐ │ │ ┌─┐ │ │ +││ │ ┌──┴─┘ │ │ ┌──┴─┴──┐ │ │ +││ │ │ │ │ │ │ │ │ +││ │ ┌▼┐ ┌──┼─┼──┐ ┌▼┐ ┌▼┐ │ │ +││ │ └─┴──┐ │ │ │ │ ┌──┴─┴──┐ └─┘ │ │ +││ │ │ │ │ ▼ │ │ │ │ +││ │ ┌▼┐ ▲ │ │ ┌▼┐ ┌▼┐ │ │ +││ │ └─┴──┐ │ │ │ │ └─┘ ┌──┴─┴──┐ │ │ +││ │ │ └──┼─┼──┘ │ │ │ │ +││ │ ┌▼┐ │ │ ┌▼┐ ┌▼┐ │ │ +││ │ └─┘ │ │ └─┘ └─┘ │ │ +││ │ │ │ │ │ +││ │ │ │ │ │ +││ │ │ │ │ │ +││ │ │ │ │ │ +││ └───────────────────────────────────┘ └──────────────────────────────────┘ │ +││ │ +└┴─────┬──▲───────────────────────────────────────────────────────────────────┘ + │ │ +┌┬─────▼──┴───────────────────────────┐ ┌┬───────────────────────────────────┐ +││ Prompt Context │ ││ LLM │ +││ │ ││ │ +││ - plan graph │ ││ GPT4-Turbo, Claude 3, BYOM │ +││ - errors ├──►│ │ +││ - code │ ││ │ +││ ◄──┼│ │ +││ │ ││ │ +││ │ ││ │ +││ │ ││ │ +└┴────────────────────────────────────┘ └┴───────────────────────────────────┘ +``` + +#### 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 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 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 its ability to fix the issue. + +#### LLM + +We only support `gpt-4-turbo-preview` at this time. + +

+ meme +

+ +## ⏱️ Benchmark + +``` +bumpgen + GPT-4 Turbo ██████████░░░░░░░░░░░ 45% (67 tasks) +``` + +We benchmarked `bumpgen` with GPT-4 Turbo against a [suite](https://github.com/xeol-io/swe-bump-bench) of version bumps with breaking changes. You can check out the evals [here](https://github.com/xeol-io/swe-bump-bench/tree/main/evals/bumpgen/v_8df9f7de936707815eb12e226517a1b0023383eb). + +## 🎁 Contributing + +Contributions are welcome! To get set up for development, see [Development](./.github/development.md). + +#### Roadmap + +- [x] codeplan +- [x] Typescript/TSX support +- [ ] `bumpgen` GitHub app +- [ ] Embeddings for different package versions +- [ ] Use test runners as an oracle +- [ ] C# support +- [ ] Java support +- [ ] Go support + +[Join](https://discord.gg/J7E9BqVHkG) our Discord community to contribute, learn more, and ask questions!