From a0bfcbb1557cfe0fab5c58d696304e4931f3d5fb Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:06:57 -0700 Subject: [PATCH 01/12] Add development guide to readme --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/README.md b/README.md index 997db56e5e..0e0a5946d6 100644 --- a/README.md +++ b/README.md @@ -3737,6 +3737,98 @@ permissive domain dedication and fallback license, so your changes must also be released under this license. +### Getting Started + +`just` is written in Rust. Use +[rustup](https://www.rust-lang.org/tools/install) to install a Rust toolchain. + +`just` is extensively tested, and all new features must be covered by at least +one unit or integration test. Unit tests are under [src](src), live alongside +the code being tested, and test code in isolation. Integration tests are in the +[tests directory](tests), and test the `just` binary from the outside by +invoking `just` on a given `justfile` and set of command-line arguments, and +checking the output. + +You should write whichever type of tests are easiest to write for your feature, +while still providing test good coverage. + +Unit tests are useful for testing new Rust functions that are used internally, +and as an aid for development. + +A good example are the unit tests which cover the +[`unindent()` function](src/unindent.rs), used to unindent triple-quoted strings +and backticks. `unindent()` has a bunch of tricky edge cases, which are easy to +exercise with unit tests that call `unindent()` directly. + +Integration tests are useful for making sure that the final behavior of the +`just` binary is correct. + +`unindent()` is also covered by integration tests which make sure that +evaluating a triple-quoted string produces the correct unindented value. +However, there are not integration tests for all possible cases, since these +are covered by faster, more concise unit tests that call `unindent()` directly. + +Existing integration are in two forms, those that use the `test!` macro, and +conventional tests which use the `Test` struct directly. The `test!` macro, +while often concise, is less flexible and harder to understand, so new tests +should use the `Test` struct. The `Test` struct is a builder which allows for +easily invoking `just` with a given `justfile`, arguments, and environment +variables, and asserting that stdout, stderr, and exit code are particular +values. + +### Contribution Workflow + +1. Make sure the feature is wanted. There should be an open issue about the + feature with a comment from [@casey](@casey) saying that it's a good idea or + seems reasonable. If there isn't, open a new issue and ask for feedback. + + There are lots of good features which can't be merged, either because they + wouldn't be backwards compatible, have an implementation which would + overcomplicate the codebase, or go against `just`'s design philosophy. + +2. Settle on the design of the feature. If the feature has multiple possible + implementations or syntaxes, make sure to nail down details in the issue. + +3. Clone `just` and start hacking. The best workflow is to have the code you're + working on in an editor side-by-side with a terminal job that re-runs tests + whenever a file changes. You can run just such a job with `just watch test`. + +4. Add a failing test for your feature. Most of the time this will be an + integration test which exercises the feature end-to-end. Look for an + appropriate file to put the test in in [tests](tests), or add a new file in + [tests](tests) and add a `mod` statement importing that file in + [tests/lib.rs](tests/lib.rs). + +5. Implement the feature. + +6. Run `just ci` to make sure that all tests, lints, and checks pass. + +7. Open a PR with the new code that is editable by maintainers. PRs often + require rebasing and minor tweaks. If the PR is not editable by maintainers, + each rebase and tweak will require a round trip of code review. Your PR may + be summarily closed if it is not editable by maintainers. + +8. Incorporate feedback. + +9. Enjoy the sweet feeling of your PR getting merged! + +### Hints + +Here are some hints to get you started with specific kinds of new features, +which you can use in addition to the contribution workflow above. + +#### Adding a New Attribute + +1. Write a new, failing integration test for the new attribute and checks that + it behaves as expected, in [tests/attributese.rs](tests/attributes.rs). + +2. Add the new attribute variant to the [`Attribute`](src/attribute.rs) enum, which + will make the parser recognize it. + +3. Implement the functionality of the new attribute. + +4. Make sure your new test passes. + ### Janus [Janus](https://github.com/casey/janus) is a tool for checking whether a change From d3506936ee927d20ddb77d93ef243cdbbd53d2b0 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:08:17 -0700 Subject: [PATCH 02/12] Reform --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0e0a5946d6..a6203fec69 100644 --- a/README.md +++ b/README.md @@ -3779,8 +3779,9 @@ values. ### Contribution Workflow 1. Make sure the feature is wanted. There should be an open issue about the - feature with a comment from [@casey](@casey) saying that it's a good idea or - seems reasonable. If there isn't, open a new issue and ask for feedback. + feature with a comment from [@casey](https://github.com/casey) saying that + it's a good idea or seems reasonable. If there isn't, open a new issue and + ask for feedback. There are lots of good features which can't be merged, either because they wouldn't be backwards compatible, have an implementation which would From 41d034a96c5c662e506132564002336e6187a689 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:09:24 -0700 Subject: [PATCH 03/12] Modify --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a6203fec69..f5a64e31f9 100644 --- a/README.md +++ b/README.md @@ -3792,7 +3792,9 @@ values. 3. Clone `just` and start hacking. The best workflow is to have the code you're working on in an editor side-by-side with a terminal job that re-runs tests - whenever a file changes. You can run just such a job with `just watch test`. + whenever a file changes. You can run such a job by installing + [cargo-watch](https://github.com/watchexec/cargo-watch) with `cargo install + cargo-watch` and running `just watch test`. 4. Add a failing test for your feature. Most of the time this will be an integration test which exercises the feature end-to-end. Look for an From bde8d06bb414bb049cb7c1460ad06f01c1f793ef Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:10:03 -0700 Subject: [PATCH 04/12] Reform --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f5a64e31f9..e90076fedb 100644 --- a/README.md +++ b/README.md @@ -3744,8 +3744,8 @@ under this license. `just` is extensively tested, and all new features must be covered by at least one unit or integration test. Unit tests are under [src](src), live alongside -the code being tested, and test code in isolation. Integration tests are in the -[tests directory](tests), and test the `just` binary from the outside by +the code being tested and test code in isolation. Integration tests are in the +[tests directory](tests) and test the `just` binary from the outside by invoking `just` on a given `justfile` and set of command-line arguments, and checking the output. From f0d0499a2cf168478ec0f13c734c9ab24f7d61b3 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:10:16 -0700 Subject: [PATCH 05/12] Adapt --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e90076fedb..3b143017d7 100644 --- a/README.md +++ b/README.md @@ -3744,7 +3744,7 @@ under this license. `just` is extensively tested, and all new features must be covered by at least one unit or integration test. Unit tests are under [src](src), live alongside -the code being tested and test code in isolation. Integration tests are in the +the code being tested, and test code in isolation. Integration tests are in the [tests directory](tests) and test the `just` binary from the outside by invoking `just` on a given `justfile` and set of command-line arguments, and checking the output. From 14486a8d8fa652eab9d21348f2603b2c8e8bf4f2 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:10:41 -0700 Subject: [PATCH 06/12] Revise --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3b143017d7..1ea29fb581 100644 --- a/README.md +++ b/README.md @@ -3742,9 +3742,9 @@ under this license. `just` is written in Rust. Use [rustup](https://www.rust-lang.org/tools/install) to install a Rust toolchain. -`just` is extensively tested, and all new features must be covered by at least -one unit or integration test. Unit tests are under [src](src), live alongside -the code being tested, and test code in isolation. Integration tests are in the +`just` is extensively tested. All new features must be covered by at least one +unit or integration test. Unit tests are under [src](src), live alongside the +code being tested, and test code in isolation. Integration tests are in the [tests directory](tests) and test the `just` binary from the outside by invoking `just` on a given `justfile` and set of command-line arguments, and checking the output. From 2d6c9fd476896a872f130ed8d7c86f8d642005e5 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:11:17 -0700 Subject: [PATCH 07/12] Reform --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1ea29fb581..83b86ed20b 100644 --- a/README.md +++ b/README.md @@ -3742,9 +3742,9 @@ under this license. `just` is written in Rust. Use [rustup](https://www.rust-lang.org/tools/install) to install a Rust toolchain. -`just` is extensively tested. All new features must be covered by at least one -unit or integration test. Unit tests are under [src](src), live alongside the -code being tested, and test code in isolation. Integration tests are in the +`just` is extensively tested. All new features must be covered by unit or +integration tests. Unit tests are under [src](src), live alongside the code +being tested, and test code in isolation. Integration tests are in the [tests directory](tests) and test the `just` binary from the outside by invoking `just` on a given `justfile` and set of command-line arguments, and checking the output. From 1e5a9b5236bb46addee0c7d333efdfe50213fbc0 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:15:49 -0700 Subject: [PATCH 08/12] Modify --- README.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 83b86ed20b..b7bd0b38d0 100644 --- a/README.md +++ b/README.md @@ -3749,32 +3749,28 @@ being tested, and test code in isolation. Integration tests are in the invoking `just` on a given `justfile` and set of command-line arguments, and checking the output. -You should write whichever type of tests are easiest to write for your feature, +You should write whichever type of tests are easiest to write for your feature while still providing test good coverage. Unit tests are useful for testing new Rust functions that are used internally, -and as an aid for development. - -A good example are the unit tests which cover the -[`unindent()` function](src/unindent.rs), used to unindent triple-quoted strings -and backticks. `unindent()` has a bunch of tricky edge cases, which are easy to -exercise with unit tests that call `unindent()` directly. +and as an aid for development. A good example are the unit tests which cover +the [`unindent()` function](src/unindent.rs), used to unindent triple-quoted +strings and backticks. `unindent()` has a bunch of tricky edge cases which are +easy to exercise with unit tests that call `unindent()` directly. Integration tests are useful for making sure that the final behavior of the -`just` binary is correct. - -`unindent()` is also covered by integration tests which make sure that -evaluating a triple-quoted string produces the correct unindented value. -However, there are not integration tests for all possible cases, since these -are covered by faster, more concise unit tests that call `unindent()` directly. - -Existing integration are in two forms, those that use the `test!` macro, and -conventional tests which use the `Test` struct directly. The `test!` macro, -while often concise, is less flexible and harder to understand, so new tests -should use the `Test` struct. The `Test` struct is a builder which allows for -easily invoking `just` with a given `justfile`, arguments, and environment -variables, and asserting that stdout, stderr, and exit code are particular -values. +`just` binary is correct. `unindent()` is also covered by integration tests +which make sure that evaluating a triple-quoted string produces the correct +unindented value. However, there are not integration tests for all possible +cases, since these are covered by faster, more concise unit tests that call +`unindent()` directly. + +Existing integration tests are in two forms, those that use the `test!` macro +and those that use the `Test` struct directly. The `test!` macro, while often +concise, is less flexible and harder to understand, so new tests should use the +`Test` struct. The `Test` struct is a builder which allows for easily invoking +`just` with a given `justfile`, arguments, and environment variables, and +checking the program's stdout, stderr, and exit code . ### Contribution Workflow @@ -3784,15 +3780,16 @@ values. ask for feedback. There are lots of good features which can't be merged, either because they - wouldn't be backwards compatible, have an implementation which would + aren't backwards compatible, have an implementation which would overcomplicate the codebase, or go against `just`'s design philosophy. 2. Settle on the design of the feature. If the feature has multiple possible - implementations or syntaxes, make sure to nail down details in the issue. + implementations or syntaxes, make sure to nail down the details in the + issue. 3. Clone `just` and start hacking. The best workflow is to have the code you're - working on in an editor side-by-side with a terminal job that re-runs tests - whenever a file changes. You can run such a job by installing + working on in an editor alongside a job that re-runs tests whenever a file + changes. You can run such a job by installing [cargo-watch](https://github.com/watchexec/cargo-watch) with `cargo install cargo-watch` and running `just watch test`. @@ -3815,6 +3812,9 @@ values. 9. Enjoy the sweet feeling of your PR getting merged! +Feel free at any time to open a draft PR with your changes for discussion and +feedback. + ### Hints Here are some hints to get you started with specific kinds of new features, From 0371c4fb0ce346f4f72935b453a490799d9c3700 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:16:35 -0700 Subject: [PATCH 09/12] Adapt --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b7bd0b38d0..992a4983bf 100644 --- a/README.md +++ b/README.md @@ -3822,8 +3822,8 @@ which you can use in addition to the contribution workflow above. #### Adding a New Attribute -1. Write a new, failing integration test for the new attribute and checks that - it behaves as expected, in [tests/attributese.rs](tests/attributes.rs). +1. Write a new, failing integration test in + [tests/attributes.rs](tests/attributes.rs) for the new attribute. 2. Add the new attribute variant to the [`Attribute`](src/attribute.rs) enum, which will make the parser recognize it. From 8b33a04ad511747f2a836366ff858f7b59d9ddf9 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:17:04 -0700 Subject: [PATCH 10/12] Enhance --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 992a4983bf..5aad2489f4 100644 --- a/README.md +++ b/README.md @@ -3822,11 +3822,9 @@ which you can use in addition to the contribution workflow above. #### Adding a New Attribute -1. Write a new, failing integration test in - [tests/attributes.rs](tests/attributes.rs) for the new attribute. +1. Write a new integration test in [tests/attributes.rs](tests/attributes.rs). -2. Add the new attribute variant to the [`Attribute`](src/attribute.rs) enum, which - will make the parser recognize it. +2. Add a new variant to the [`Attribute`](src/attribute.rs) enum. 3. Implement the functionality of the new attribute. From 611aadb0665e91897502fd157c4dabf16d0bd8fd Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:17:28 -0700 Subject: [PATCH 11/12] Adapt --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5aad2489f4..507d66f1c2 100644 --- a/README.md +++ b/README.md @@ -3828,7 +3828,7 @@ which you can use in addition to the contribution workflow above. 3. Implement the functionality of the new attribute. -4. Make sure your new test passes. +4. Run `just ci` to make sure that all tests pass. ### Janus From f1a8ca02d85f0767a79485201551906375dbd075 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 6 Jul 2024 12:19:29 -0700 Subject: [PATCH 12/12] Adapt --- README.md | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 507d66f1c2..fe2a549163 100644 --- a/README.md +++ b/README.md @@ -3743,20 +3743,23 @@ under this license. [rustup](https://www.rust-lang.org/tools/install) to install a Rust toolchain. `just` is extensively tested. All new features must be covered by unit or -integration tests. Unit tests are under [src](src), live alongside the code -being tested, and test code in isolation. Integration tests are in the -[tests directory](tests) and test the `just` binary from the outside by -invoking `just` on a given `justfile` and set of command-line arguments, and -checking the output. +integration tests. Unit tests are under +[src](https://github.com/casey/just/blob/master/src), live alongside the code +being tested, and test code in isolation. Integration tests are in the [tests +directory](https://github.com/casey/just/blob/master/tests) and test the `just` +binary from the outside by invoking `just` on a given `justfile` and set of +command-line arguments, and checking the output. You should write whichever type of tests are easiest to write for your feature while still providing test good coverage. Unit tests are useful for testing new Rust functions that are used internally, and as an aid for development. A good example are the unit tests which cover -the [`unindent()` function](src/unindent.rs), used to unindent triple-quoted -strings and backticks. `unindent()` has a bunch of tricky edge cases which are -easy to exercise with unit tests that call `unindent()` directly. +the +[`unindent()` function](https://github.com/casey/just/blob/master/src/unindent.rs), +used to unindent triple-quoted strings and backticks. `unindent()` has a bunch +of tricky edge cases which are easy to exercise with unit tests that call +`unindent()` directly. Integration tests are useful for making sure that the final behavior of the `just` binary is correct. `unindent()` is also covered by integration tests @@ -3795,9 +3798,11 @@ checking the program's stdout, stderr, and exit code . 4. Add a failing test for your feature. Most of the time this will be an integration test which exercises the feature end-to-end. Look for an - appropriate file to put the test in in [tests](tests), or add a new file in - [tests](tests) and add a `mod` statement importing that file in - [tests/lib.rs](tests/lib.rs). + appropriate file to put the test in in + [tests](https://github.com/casey/just/blob/master/tests), or add a new file + in [tests](https://github.com/casey/just/blob/master/tests) and add a `mod` + statement importing that file in + [tests/lib.rs](https://github.com/casey/just/blob/master/tests/lib.rs). 5. Implement the feature. @@ -3822,9 +3827,12 @@ which you can use in addition to the contribution workflow above. #### Adding a New Attribute -1. Write a new integration test in [tests/attributes.rs](tests/attributes.rs). +1. Write a new integration test in + [tests/attributes.rs](https://github.com/casey/just/blob/master/tests/attributes.rs). -2. Add a new variant to the [`Attribute`](src/attribute.rs) enum. +2. Add a new variant to the + [`Attribute`](https://github.com/casey/just/blob/master/src/attribute.rs) + enum. 3. Implement the functionality of the new attribute.