Skip to content

Commit

Permalink
Update the README
Browse files Browse the repository at this point in the history
  • Loading branch information
@Stephan202
Stephan202 committed Nov 5, 2023
1 parent ab481cd commit dcbc56f
Showing 1 changed file with 53 additions and 43 deletions.
96 changes: 53 additions & 43 deletions workshop/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,32 @@
# Error Prone Workshop

The slides of the workshop:

[EPS Workshop JFall][eps-workshop-jfall]
The slides of the workshop: [EPS Workshop JFall][eps-workshop-jfall].

## Initial setup of the workshop

1. Start with forking `PicnicSupermarket/error-prone-support` repository on
GitHub. Make sure to unselect `Copy the master branch only`.
1. Start by forking the [`PicnicSupermarket/error-prone-support`][eps-github]
repository on GitHub. Make sure to deselect _Copy the master branch only_.
2. Set the `workshop` branch as the `default` branch in the fork. Go to
`Settings -> General -> Default Branch` for this.
3. Go to the `Actions` tab of your repository and click the green `Enable`
_Settings -> General -> Default Branch_ for this.
3. Go to the `Actions` tab of your repository and click the green _Enable_
button to allow running of workflows.
4. Clone the repository locally.
5. Make sure to run a `mvn clean install` in the root of this repository.
5. Make sure to run `mvn clean install` in the root of this repository.
6. Open your code editor and familiarize yourself with the project structure.

If you are a macOS user, please run the following commands:
Next to unit tests, the workshop comes with an integration testing framework
that relies on `grep` and `sed`. So if you are a macOS user, please run the
following commands:
* `brew install grep`
* `brew install gsed`

Our testing framework relies on `grep` and `sed`.

To verify that the test setup works, please run this command:

```sh
./integration-tests/checkstyle-10.12.4.sh
```

The script should end with the following text:
The script should end with the following output:
```
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
Expand All @@ -39,8 +37,8 @@ Inspecting changes...
Inspecting emitted warnings...
```

Try to run the `WorkshopRefasterRulesTest` and see if it runs.
You might see the following error:
With IntelliJ IDEA, try to run the `WorkshopRefasterRulesTest` test. You might
see the following error:

```
java: exporting a package from system module jdk.compiler is not allowed with --release
Expand All @@ -52,10 +50,10 @@ cross-compilation (Java 9 and later)_.

Now the project is ready for the rest of the workshop.

Important to know is that for every commit and pull request a GitHub Action
will be triggered to run the integration test. After a failure, there is an
option to download artifacts that contain information on the changes that are
introduced by the new rules.
Important to note is that for every commit pushed and pull request opened, a
GitHub Action will be triggered to run the integration tests. In case of a
failure, there is the option to download artifacts that contain information on
the changes that are introduced by the new rules.


## Part 1: Writing Refaster rules
Expand All @@ -64,25 +62,29 @@ During this part of the workshop we will implement multiple Refaster rules.

Go to the `workshop` module and open the
`tech.picnic.errorprone.workshop.refasterrules` package. There you can find one
example and 5 different exercises to do.
Make sure to check out the `WorkshopRefasterRulesTest.java` class where you can
enable tests. Per assignment there is a test in this class that one can enable
(by dropping the `@Disabled` annotation) which runs the test. The assignment is
to implement or improve the Refaster rule such that the build succeeds.
example and 5 different exercises to do. Make sure to check out the
`WorkshopRefasterRulesTest.java` class where you can enable tests. Per
assignment there is a test in this class that one can enable (by dropping the
`@Disabled` annotation) to validate your changes. The goal is to implement or
improve the Refaster rules such that the enabled tests pass.

Tips:
* The `XXX:` comments explains what needs to happen.
* See the associated test cases of the Refaster rule by looking for the name of the Refaster rule
prefixed with `test`. For example, the `WorkshopAssignment0Rules.java` rule collection has a Refaster rule named `ExampleStringIsEmpty`.
In the `WorkshopAssignment0RulesTestInput.java` and `WorkshopAssignment0RulesTestOutput.java` file there is
a `testExampleStringIsEmpty` method that shows the input and output to test the Refaster rule.
* See the test cases for each Refaster rule by looking for the name of the
Refaster rule prefixed with `test`. For example, the
`WorkshopAssignment0Rules.java` rule collection has a Refaster rule named
`ExampleStringIsEmpty`. In the `WorkshopAssignment0RulesTestInput.java` and
`WorkshopAssignment0RulesTestOutput.java` files there is a
`testExampleStringIsEmpty` method that shows the input and output to test the
Refaster rule.

### Validating changes with the integration tests

After finishing the 5 assignments, commit and push the result. This will trigger the integration test
which will run for about 10 minutes. When the build finished, inspect the uploaded artifacts
and look at the file containing `diff-of-diffs` in the name. It shows the impact of the rules that you
wrote when they are applied on Checkstyle!
After finishing the assignments, commit and push the result. This will trigger
execution of the integration tests, which will run for about 10 minutes. When
the build finished, inspect the uploaded artifacts and look at the file with
`diff-of-diffs` in the name. It shows the impact of the rules that you wrote
when they are applied to Checkstyle!

If you want to test this locally, run the following commands:

Expand All @@ -96,27 +98,34 @@ XXX: Write how to inspect the changes.

## Part 2: Writing Error Prone checks

During this part of the workshop we will implement multiple Error Prone BugCheckers.
The assignments are split in different parts. Make sure to get the associated tests green.
Drop the `@Disabled` annotation to run the test. Every `BugChecker` has an associated test class
which has the same class name but suffixed with `Test`.
Go to the
During this part of the workshop we will implement multiple Error Prone
`BugChecker`s. The assignments are split into different parts. Make sure to get
the associated tests green. Drop the `@Disabled` annotation to run a test.
Every `BugChecker` has an associated test class which has the same class name
but suffixed with `Test`. Go to the

XXX: This text is incomplete ^.

A recommended order of solving the assignments (but not required):
XXX: @Rick write this.

Some utility classes that you can use:
* ASTHelpers - contains many common operations on the AST.
* Types - for doing comparisons between Java types.
* SuggestedFixes - contains helper methods for creating fixes of BugPatterns.
* `com.google.errorprone.util.ASTHelpers`: contains many common operations on
the AST.
* `Types`: for doing comparisons between Java types.
* `com.google.errorprone.fixes.SuggestedFixes`: contains helper methods for
creating `Fix`es.

XXX: Which type does `Types` refer to?


### Validating changes with the integration tests

After finishing the 2 assignments, commit and push the result. This will trigger the integration test
which will run for about 10 minutes. When the build finished, inspect the uploaded artifacts
and look at the file containing `diff-of-diffs` in the name. It shows the impact of the rules that you
wrote when they are applied on Checkstyle!
After finishing the assignments, commit and push the result. This will trigger
execution of the integration tests, which will run for about 10 minutes. When
the build finished, inspect the uploaded artifacts and look at the file with
`diff-of-diffs` in the name. It shows the impact of the rules that you wrote
when they are applied to Checkstyle!

If you want to test this locally, run the following commands:

Expand Down Expand Up @@ -144,4 +153,5 @@ You can use this chance to automatically:
If you have an idea, feel free to mention this during the workshop and get some
ideas on how to implement it!

[eps-github]: https://github.com/PicnicSupermarket/error-prone-support
[eps-workshop-jfall]: https://drive.google.com/file/d/14UiIZNJxpiFSnHNjXVAyvWex2WWXQ8Ln/view

0 comments on commit dcbc56f

Please sign in to comment.