1# How to Contribute 2 3We'd love to accept your patches and contributions to this project. There are 4just a few small guidelines you need to follow. 5 6## Contributor License Agreement 7 8Contributions to this project must be accompanied by a Contributor License 9Agreement (CLA). You (or your employer) retain the copyright to your 10contribution; this simply gives us permission to use and redistribute your 11contributions as part of the project. Head over to 12<https://cla.developers.google.com/> to see your current agreements on file or 13to sign a new one. 14 15You generally only need to submit a CLA once, so if you've already submitted one 16(even if it was for a different project), you probably don't need to do it 17again. 18 19## Code reviews 20 21All submissions, including submissions by project members, require review. We 22use GitHub pull requests for this purpose. Consult 23[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 24information on using pull requests. 25 26## Community Guidelines 27 28This project follows 29[Google's Open Source Community Guidelines](https://opensource.google/conduct/). 30 31## API verification 32 33For changes that involves API changes(new API, API signature change), please also update [api.base](./api/api.base) file. You can monitor api change with `./gradlew :api:apiCheck`, and`./gradlew :api:updateApi` to generate new api signature. 34 35## Testing 36For incoming PRs, we would like to request changes covered by tests for good practice. 37We do end-to-end test for KSP, which means you need to write a lightweight processor to be loaded with KSP for testing. 38The form of the test itself is flexible as long as the logic is being covered. 39 40Here are some [sample test processors](compiler-plugin/src/test/kotlin/com/google/devtools/ksp/processor) for your reference. 41 42#### Steps for writing a test 43* KSP needs to be built with JDK 11+, because of some test dependencies. 44* Create a test processor under the sample processor folder. 45it should be extending [AbstractTestProcessor](compiler-plugin/src/test/kotlin/com/google/devtools/ksp/processor/AbstractTestProcessor.kt) 46* Write your logic by overriding corresponding functions. 47 * Test is performed by running test processor and get a collection of test results in the form of List<String>. 48 * Make sure you override toResult() function to collect test result. 49 * Leverage visitors for easy traverse of the test case. 50 * To help with easy testing, you can create an annotation for test, and annotate the specific part of the code to avoid doing 51 excess filtering when traveling along the program. 52* Write your test case to work with test processor. 53 * Create a test kt file under [testData](compiler-plugin/testData/api) folder. 54 Every kt file under this folder corresponds to a test case. 55 * Inside the test file: 56 * [optional] Add ```// WITH_RUNTIME``` to the top if you need access to standard library. 57 * Add ```// TEST PROCESSOR:<Your test processor name>``` to provide the test processor for this test case. Processors can 58 be reused if necessary. 59 * Immediately after test processor line, start your expected result lines. Every line should start with 60 ```// ```(with a space after //) 61 * Add ```// END``` to indicate end of expected test result. 62 * Then follows virtual files section till the end of test file. 63 * You can use ```// FILE: <file name>``` to create files that will be available at run time of the test. 64 * E.g. ```// FILE: a.kt``` will result in a file named ```a.kt``` at run time. 65* Add new test to [test suite](compiler-plugin/src/test/java/com/google/devtools/ksp/test/KotlinKSPTestGenerated.java) 66* Run generated tests with ```:compiler-plugin:test``` gradle task. 67 * This will execute all tests in KSP test suite. To run your test only, specify the test name with 68 ```--tests "com.google.devtools.ksp.test.KotlinKSPTestGenerated.<name of your generated test>"``` 69 * Make sure your change is not breaking any existing test as well :). 70