diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a492bc02..7cdc1113 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,5 @@ +# Overview + This repository is a Racket package called Resyntax, which is a refactoring and static analysis tool for Racket code. It analyzes code using "refactoring rules" written in a domain-specific sublanguage of Racket and implemented using @@ -5,6 +7,8 @@ Racket's macro system. Resyntax then uses these rules to suggest ways people can improve their Racket code. See the [Resyntax documentation][1] and [Racket website][2] for more information. +## Adding New Refactoring Rules + When trying to add a new refactoring rule to Resyntax's default recommendations, pay special attention to the sections in the Resyntax documentation on [what makes a good refactoring rule][3] and on @@ -16,16 +20,43 @@ how to run it. Beware that Resyntax is *not* a `raco` command. Run it using `resyntax fix` or `resyntax analyze`, not `raco resyntax fix` or `raco resyntax analyze`. -When creating a pull request, avoid being overly verbose in the pull -request description. Keep descriptions to a single paragraph. If you need to -include example code, limit it to one or two small blocks. Do not write -lengthy, detailed explanations or documentation in the PR description. - If you want to experiment with new refactoring rules you've created, consider doing so by cloning the [DrRacket][6], [Herbie][7], or [Typed Racket][8] repositories and running Resyntax on them. These repositories contain a lot of Racket code and are good candidates for testing new refactoring rules. +## Pull Request Style Conventions + +When creating a pull request, avoid being overly verbose in the pull +request description. Keep descriptions to a single paragraph. If you need to +include example code, limit it to one or two small blocks. Do not write +lengthy, detailed explanations or documentation in the PR description. Avoid +mentioning things that are obvious from the code changes themselves, such as +lists of files changed. Reserve the PR description for only the most essential +information, and err on the side of omission. There is nothing wrong with a +pull request description that is just a single sentence and a mention of what +issue number is being addressed. + +## Code Coverage + +When writing tests, you can use the [`raco cover`][9] command to check the +code coverage of your test cases. The command `raco cover path/to/file.rkt` +will generate an HTML report showing what code is covered by running the +indicated files. To check coverage for the whole repository, you can run +this command: + +```bash +raco cover --suppress-log-execution --package resyntax +``` + +The `--suppress-log-execution` flag is necessary to avoid a bug in `raco cover` +related to Racket's logging system. The `raco cover` tool has a few other sharp +edges like this; see its documentation for more details. + +Pull requests should aim for high code coverage, and an integration with Coveralls +is set up to help track coverage over time. You can view the Coveralls report for +the entire repository at [this link][10]. + [1]: https://docs.racket-lang.org/resyntax/ [2]: https://racket-lang.org/ [3]: https://docs.racket-lang.org/resyntax/Refactoring_Rules_and_Suites.html#%28part._.What_.Makes_a_.Good_.Refactoring_.Rule_%29 @@ -34,3 +65,5 @@ of Racket code and are good candidates for testing new refactoring rules. [6]: https://github.com/racket/drracket [7]: https://github.com/herbie-fp/herbie [8]: https://github.com/racket/typed-racket +[9]: https://docs.racket-lang.org/cover/ +[10]: https://coveralls.io/github/jackfirth/resyntax diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index 3546128a..ca08d9fb 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -23,4 +23,5 @@ jobs: - uses: Bogdanp/setup-racket@v1.14 with: version: stable + - run: raco pkg install --batch --auto cover - run: raco pkg install --batch --auto --link --name resyntax