Skip to content

Commit 2d092c5

Browse files
olganaumenkoolganaumenko
authored
Contributing guide and related docs updated (#861)
1 parent d9b7076 commit 2d092c5

File tree

4 files changed

+158
-82
lines changed

4 files changed

+158
-82
lines changed

‎CONTRIBUTING.md

Lines changed: 90 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,117 @@
1-
# How to contribute to UTBot Java
1+
# UnitTestBot contributing guide
22

3-
To begin with, we are very thankful for your time and willingness to read this and contribute!
3+
---
44

5-
The following guideline should help you with suggesting changes to our project, so feel free to use it for your contribution. 😃
5+
## Welcome!
66

7+
Hello and thanks for reading this!
78

8-
## I\`ve found a bug! How to report?
9+
As the UnitTestBot core team we develop tools for automated unit test generation to help programmers test their code
10+
in a more effective way with less effort. We believe that software development is great fun when you spend your time
11+
finding creative solutions and automate the things you already know. If you are curious about making test generation
12+
fast, smart and reliable, we are happy to invite you for contributing!
913

10-
First of all, please check our [Issues](https://github.com/UnitTestBot/UTBotJava/issues) — this bug may have already been reported, and you just don\`t need to spend your time on a new one.
14+
We welcome absolutely everyone. With one big and kind request: please follow these guidelines to make our communication smooth and to keep UnitTestBot improving.
1115

12-
If you haven\`t found the relevant issue, don\`t hesitate to [create a new one](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=bug_report.md&title=), including as much detail as possible — the pre-made template will assist you in it.
16+
## Contributions we are looking for
1317

14-
In case you already have a PR with a solution, please remain so amazing and link it with the created issue.
18+
There are so many ways to contribute. Choose yours and find the relevant short guide below.
1519

20+
|(1) Choose what you like and check the guideline:| (2) Contribute: |
21+
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
22+
|Reporting a bug| Create a [bug reporting issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=bug_report.md&title=) |
23+
|Suggesting a feature| Create a [feature suggestion issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=feature_request.md&title=) |
24+
|Contributing the code (bug fix or feature implementation)| Create a pull request |
25+
|Reproducing a reported bug| Comment on the issue |
26+
|Testing a pull request| Comment on the pull request |
27+
|Improving documentation| Create an issue<br/>Create a pull request<br/>Comment on issues and PRs |
28+
|Sharing ideas| Start the [Discussion](https://github.com/UnitTestBot/UTBotJava/discussions) or join the existing one |
1629

17-
## I have an improvement suggestion!
18-
Want a new feature or to change the existing one? We are very welcome your fresh ideas. 😃
30+
# How to submit a contribution
1931

20-
Please [create an issue](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=feature_request.md&title=) with your proposal and describe your idea with full information about it. By adding some examples you also bring much happiness to our souls!
32+
## Reporting a bug
2133

22-
Give us some time to review your proposal and provide you with our feedback. It will be decided who is preparing the pull request: we may need your help or we will take care of it all. 🙂
34+
1. Check if the bug (a true bug!) has already been reported: search through [UnitTestBot issues](https://github.com/UnitTestBot/UTBotJava/issues). Please, don't duplicate.
35+
2. Check with the [Naming and labeling conventions](Conventions.md).
36+
3. Make sure you have all the necessary information as per [template](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=bug_report.md&title=) and create the bug reporting issue.
2337

38+
## Requesting a feature
2439

25-
## Coding conventions
26-
Our team adheres to the defined requirements to coding style to optimize for readability. You can take a look on this [Coding style guide](https://github.com/saveourtool/diktat/blob/master/info/guide/diktat-coding-convention.md) to better understand what we expect to see in your code.
40+
1. Check if the feature has already been requested: search through [UnitTestBot issues](https://github.com/UnitTestBot/UTBotJava/issues).
41+
2. Check with our [Naming and labeling conventions](Conventions.md).
42+
3. Make sure you are able to provide all the necessary information as per [template](https://github.com/UnitTestBot/UTBotJava/issues/new?assignees=&labels=&template=feature_request.md&title=) and create the feature request issue.
2743

44+
## Contributing the code (bug fix or feature implementation)
2845

29-
## Naming conventions
30-
We have been using GitHub for a while, and now we have a couple of tips for naming issues, commits and pull requests (PRs). You are welcome to stick to them too 🙂
46+
### "Good first issue"
3147

32-
Our favorite recipes are:
48+
If you have little experience in contributing, try to resolve the issues labeled as the ["good first"](https://github.com/UnitTestBot/UTBotJava/contribute) ones.
3349

34-
**issue title = feature request or bug description + issue ID**
50+
### Small or "obvious" fixes
3551

36-
**commit message = PR title = fix description + issue ID + (PR number)**
52+
Do you need to create an issue if you want to fix a bug?
3753

38-
How to insert the issue ID into the commit message and the PR title?<br>
39-
— Manually.
54+
* Quick fix → no issue → pull request.
55+
* Takes time to fix → detailed issue → pull request.
4056

41-
How to append the PR number to the PR title?<br>
42-
— It appends automatically.
57+
### General flow for contributing code
4358

44-
How to insert the PR number into the commit message?<br>
45-
— *Push* the feature branch + *Create pull request* on GitHub and then →<br>
46-
1) The preferred and the easiest flow:
47-
<br>*Squash and merge* on GitHub → the PR number automatically appends to the resulting commit message
48-
2) The flow for advanced users:
49-
<br>(a) squash the commits locally → insert the PR number in parentheses (!) manually into the resulting commit
50-
message + *Force Push* the resulting commit → *Rebase and merge* on GitHub
51-
<br>or
52-
<br>(b) change the commit message locally → insert the PR number in parentheses (!) manually + *Force Push* the
53-
commit → *Rebase and merge* on GitHub
59+
1. Make sure you've carefully read the [Legal notes](#Legal-notes)!
60+
2. Create your own fork of the code.
61+
3. Clone the forked repository to your local machine.
62+
4. Implement changes. Please refer to the [Developer guide](DEVNOTE.md) for **system requirements**, **code
63+
style** and
64+
**steps for building the project**.
65+
5. Test your code:
66+
* Before creating the pull request perform the tests you find necessary for your code changes.
67+
* When implementing something new, it's great to find real users and ask them to try out your feature — to prove
68+
the necessity and quality of your suggestion.
69+
6. Check with the [Naming and labeling conventions](Conventions.md).
70+
7. Create the pull request, and you'll see if the automated tests pass on GitHub. Your reviewer will possibly recommend
71+
you more tests.
5472

73+
## Reproducing a reported bug
5574

56-
## How to setup development environment?
75+
If you reproduce an existing issue and it helps to get some additional context on the problem, feel free to comment on the issue.
5776

58-
Please refer [Developer guide](https://github.com/UnitTestBot/UTBotJava/blob/main/DEVNOTE.md) to setup developer environment, build and run UTBot.
77+
## Testing a pull request
5978

79+
You can merge a pull request into your local copy of the project and test the changes. If you find something you'd like to share, add the outcome of your testing in a comment on the pull request.
6080

61-
## How to test you PR?
81+
## Improving documentation
6282

63-
Currently, not all checks are automized. It's required to do manual testing after PR.
83+
Here at UnitTestBot we regard documentation as code. It means that the general flow for writing and reviewing docs
84+
is the same as for the code. If you'd like to improve the existing docs or to add something new, please follow the flow:
85+
86+
1. Make sure you've carefully read the [Legal notes](#Legal-notes)!
87+
2. Create your own fork of the code.
88+
3. Clone the forked repository to your local machine.
89+
4. Implement changes to docs (change the existing doc or create a new one). Usually, we create a new doc for a new feature, not for the small fixes. You are not obliged to write a detailed text about the feature you implement. You have to only describe it properly in both the related issue and the pull request, but it will be great if you still provide some docs.
90+
6. Check with the [Naming and labeling conventions](Conventions.md).
91+
7. Create the pull request, and we'll review it.
92+
93+
* You can request a new doc — create an issue, using the [guide for a feature request](#Requesting-a-feature).
94+
* You can comment on the docs-related issues or PRs.
95+
96+
## Sharing ideas
97+
98+
We have a lot of new ideas, but we always need more!
99+
100+
These are our main areas of interest:
101+
102+
* technologies for code analysis, generating unit tests, e. g. symbolic execution, fuzzing, machine learning, etc.;
103+
* real-life examples of using UnitTestBot, as well as possible use cases, scenarios and user stories;
104+
* practices and problems or UX research related to unit testing with or without automated test generation tools.
105+
106+
If you are keen on these things too, please share your ideas with us. Even if they are sketchy and not ready for being implemented or even requested right now, go ahead and join the existing [Discussions](https://github.com/UnitTestBot/UTBotJava/discussions) or [start](https://github.com/UnitTestBot/UTBotJava/discussions/new) the new one.
107+
108+
# Code review process
109+
Please choose [denis-fokin](https://github.com/denis-fokin) as a reviewer. He will reassign your PR to someone else from the core team, if necessary.
110+
111+
We do our best in reviewing, but we can hardly specify the exact timeout for it. Be sure that we'll certainly answer your pull request!
112+
113+
# Legal notes
114+
115+
By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](https://github.com/UnitTestBot/UTBotJava/blob/main/LICENSE).
116+
117+
Feel free to [contact us directly](https://www.utbot.org/contact/) if that's a concern.

‎Conventions.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Naming and labeling conventions
2+
3+
---
4+
5+
## Naming conventions
6+
7+
### How to name a branch
8+
9+
We use feature branches for development. Our best practice is to use the "my-github-username" prefix for each branch and to split words with the low line, e.g.:
10+
11+
**_githubuser/my_feature_branch_**
12+
13+
### How to name issues, commits and pull requests
14+
15+
We have been using GitHub for a while, and now we have a couple of tips for naming issues, commits and pull requests (
16+
PRs). You are welcome to stick to them too 🙂
17+
18+
Our favorite recipes are:
19+
20+
**issue title = feature request or bug description + issue ID**
21+
22+
**commit message = PR title = fix description + issue ID + (PR number)**
23+
24+
How to insert the issue ID into the commit message and the PR title?<br>
25+
— Manually.
26+
27+
How to append the PR number to the PR title?<br>
28+
— It appends automatically.
29+
30+
How to insert the PR number into the commit message?<br>
31+
— *Push* the feature branch + *Create pull request* on GitHub and then →<br>
32+
33+
1) The preferred and the easiest flow:
34+
<br>*Squash and merge* on GitHub → the PR number automatically appends to the resulting commit message
35+
2) The flow for advanced users:
36+
<br>(a) squash the commits locally → insert the PR number in parentheses (!) manually into the resulting commit
37+
message + *Force Push* the resulting commit → *Rebase and merge* on GitHub
38+
<br>or
39+
<br>(b) change the commit message locally → insert the PR number in parentheses (!) manually + *Force Push* the
40+
commit → *Rebase and merge* on GitHub
41+
42+
## Labeling conventions
43+
44+
To choose the proper labels for your issue or PR, refer to the [Label usage guidelines](https://github.com/UnitTestBot/UTBotJava/wiki/Labels-usage-guidelines).

‎DEVNOTE.md

Lines changed: 15 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,24 @@
1-
# UTBot Java Developer Guide
2-
3-
Here are the steps for you to jump into UTBot Java.
4-
5-
## Install UTBot Java from source
6-
1. Clone UTBot Java repository via [Git](https://github.com/UnitTestBot/UTBotJava.git)
7-
2. Open project in IDE
1+
# UnitTestBot developer guide
82

9-
![image](https://user-images.githubusercontent.com/106974353/174806216-9d4969b4-51fb-4531-a6d0-94e3734a437a.png)
3+
---
104

11-
⚠️ Important don\`t forgets at this step:
5+
When you have the forked repository on your local machine, you are almost ready to build your own version of UnitTestBot.
126

13-
✔️ check your Project SDK and Gradle SDK are of 1.8 Java version.
7+
💡 Before you start coding, please check the [system requirements](SystemRequirements.md) and find instructions on
8+
configuring development environment.
149

15-
![image](https://user-images.githubusercontent.com/106974353/174812758-fcbabb5b-0411-48d7-aefe-6d69873185e3.png)
16-
![image](https://user-images.githubusercontent.com/106974353/174806632-ed796fb7-57dd-44b5-b499-e9eeb0436f15.png)
10+
💡 Get to know the [code style](https://github.com/saveourtool/diktat/blob/master/info/guide/diktat-coding-convention.md) we are used to.
1711

18-
✔️ check your System environment variables: the KOTLIN_HOME variable path should be set up
12+
## How to build UnitTestBot with your improvements
1913

20-
![image](https://user-images.githubusercontent.com/106974353/175059333-4f3b0083-7964-4886-8fcd-48c475fc1fb3.png)
14+
The project structure is mostly straightforward and the modules are self-explanatory, e.g.:
2115

16+
* ```utbot-framework``` — everything related to UnitTestBot engine (including tests);
17+
* ```utbot-intellij``` — IDE plugin implementation;
18+
* ```utbot-sample``` — a framework with examples to demonstrate engine capacity.
2219

23-
3. Open Gradle tool window
24-
4. Launch Task utbot > Tasks > build > assemble
25-
26-
![image](https://user-images.githubusercontent.com/106974353/174807962-18c648fd-b67d-4556-90df-eee690abe6e2.png)
27-
28-
5. Wait for the build to be completed
29-
30-
Done! You\`re awesome and ready for digging the code. 😃
31-
32-
33-
## Development of UTBot Java with IntelliJ IDEA
34-
35-
The majority of the code is written in Kotlin.
36-
37-
The project is divided into Gradle subprojects. The most significant of them are:
38-
1. utbot-framework — all about the engine and tests for it
39-
40-
2. utbot-intellij — IDE plugin
41-
42-
3. utbot-sample — a framework with examples to demonstrate engine capacity
43-
44-
## Testing
45-
46-
The project contains many tests. They are usually placed in test root of the particular Gradle subproject.
47-
48-
While developing, it\`s useful to run tests from utbot-framework subproject. The majority of tests from this subproject generate tests for samples from the utbot-sample subproject.
20+
Learn UnitTestBot from inside and implement changes. To verify your improvements open Gradle tool window in IntelliJ IDEA:
4921

22+
* to _run/debug plugin_ in IntelliJ IDEA choose and run the task: **utbot → utbot-intellij → intellij → runIde**;
23+
* to _compile plugin_ choose and run the task: **utbot → utbot-intellij → intellij → buildPlugin**. The resulting ZIP
24+
file is located at ```utbot-intellij/build/distributions```.

‎SystemRequirements.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,18 @@ you have to install
1414

1515
- JDK 11;
1616

17-
- Kotlin 1.7.0 or later;
17+
- Kotlin 1.7.0 or later.
1818

19-
you also have to check if
19+
Please check your development environment:
2020

21-
- ```JAVA_HOME``` environment variable contains the path to JDK 11 installation directory;
21+
- ```JAVA_HOME``` environment variable should contain the path to JDK 11 installation directory;
2222

23-
- ```PATH``` environment variable contains the path to the ```bin``` folder of JDK 11 installation directory;
23+
- ```PATH``` environment variable should contain the path to the ```bin``` folder of JDK 11 installation directory;
2424

25-
- ```KOTLIN_HOME``` environment variable contains the path to the ```kotlinc``` folder of Kotlin (1.7.0 or later) installation
26-
directory.
25+
- ```KOTLIN_HOME``` environment variable should contain the path to the ```kotlinc``` folder of Kotlin (1.7.0 or later) installation
26+
directory;
27+
- Project SDK (1) and Gradle SDK (2) should be set to JDK 11:
28+
<br>(1) **IntelliJ IDEA → File → Project Structure → Project Settings → Project → SDK**,
29+
<br>(2) **IntelliJ IDEA → File → Settings → Build, Execution, Deployment → Build Tools → Gradle**.
2730

2831
Please note: if the environment variables lead to unsupported JDK or Kotlin versions, you won't be able to build the UnitTestBot project.

0 commit comments

Comments
 (0)