CONTRIBUTING.md 4.85 KB
Newer Older
Kalen Michael's avatar
Kalen Michael committed
1
2
3
4
5
6
7
8
9
10
## Contributing to YOLOv5 🚀

We love your input! We want to make contributing to YOLOv5 as easy and transparent as possible, whether it's:

- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing a new feature
- Becoming a maintainer

Glenn Jocher's avatar
Glenn Jocher committed
11
12
YOLOv5 works so well due to our combined community effort, and for every small improvement you contribute you will be
helping push the frontiers of what's possible in AI 😃!
Kalen Michael's avatar
Kalen Michael committed
13
14

## Submitting a Pull Request (PR) 🛠️
Glenn Jocher's avatar
Glenn Jocher committed
15

Glenn Jocher's avatar
Glenn Jocher committed
16
17
18
Submitting a PR is easy! This example shows how to submit a PR for updating `requirements.txt` in 4 steps:

### 1. Select File to Update
Glenn Jocher's avatar
Glenn Jocher committed
19

Glenn Jocher's avatar
Glenn Jocher committed
20
Select `requirements.txt` to update by clicking on it in GitHub.
Glenn Jocher's avatar
Glenn Jocher committed
21
<p align="center"><img width="800" alt="PR_step1" src="https://user-images.githubusercontent.com/26833433/122260847-08be2600-ced4-11eb-828b-8287ace4136c.png"></p>
Glenn Jocher's avatar
Glenn Jocher committed
22
23

### 2. Click 'Edit this file'
Glenn Jocher's avatar
Glenn Jocher committed
24

Glenn Jocher's avatar
Glenn Jocher committed
25
Button is in top-right corner.
Glenn Jocher's avatar
Glenn Jocher committed
26
<p align="center"><img width="800" alt="PR_step2" src="https://user-images.githubusercontent.com/26833433/122260844-06f46280-ced4-11eb-9eec-b8a24be519ca.png"></p>
Glenn Jocher's avatar
Glenn Jocher committed
27
28

### 3. Make Changes
Glenn Jocher's avatar
Glenn Jocher committed
29

Glenn Jocher's avatar
Glenn Jocher committed
30
Change `matplotlib` version from `3.2.2` to `3.3`.
Glenn Jocher's avatar
Glenn Jocher committed
31
<p align="center"><img width="800" alt="PR_step3" src="https://user-images.githubusercontent.com/26833433/122260853-0a87e980-ced4-11eb-9fd2-3650fb6e0842.png"></p>
Glenn Jocher's avatar
Glenn Jocher committed
32
33

### 4. Preview Changes and Submit PR
Glenn Jocher's avatar
Glenn Jocher committed
34
35
36
37

Click on the **Preview changes** tab to verify your updates. At the bottom of the screen select 'Create a **new branch**
for this commit', assign your branch a descriptive name such as `fix/matplotlib_version` and click the green **Propose
changes** button. All done, your PR is now submitted to YOLOv5 for review and approval 😃!
Glenn Jocher's avatar
Glenn Jocher committed
38
<p align="center"><img width="800" alt="PR_step4" src="https://user-images.githubusercontent.com/26833433/122260856-0b208000-ced4-11eb-8e8e-77b6151cbcc3.png"></p>
Glenn Jocher's avatar
Glenn Jocher committed
39
40

### PR recommendations
Kalen Michael's avatar
Kalen Michael committed
41
42

To allow your work to be integrated as seamlessly as possible, we advise you to:
Glenn Jocher's avatar
Glenn Jocher committed
43
44
45
46
47
48

- ✅ Verify your PR is **up-to-date with origin/master.** If your PR is behind origin/master an
  automatic [GitHub actions](https://github.com/ultralytics/yolov5/blob/master/.github/workflows/rebase.yml) rebase may
  be attempted by including the /rebase command in a comment body, or by running the following code, replacing 'feature'
  with the name of your local branch:

Kalen Michael's avatar
Kalen Michael committed
49
50
51
52
53
54
55
56
```bash
git remote add upstream https://github.com/ultralytics/yolov5.git
git fetch upstream
git checkout feature  # <----- replace 'feature' with local branch name
git merge upstream/master
git push -u origin -f
```

Glenn Jocher's avatar
Glenn Jocher committed
57
58
59
- ✅ Verify all Continuous Integration (CI) **checks are passing**.
- ✅ Reduce changes to the absolute **minimum** required for your bug fix or feature addition. _"It is not daily increase
  but daily decrease, hack away the unessential. The closer to the source, the less wastage there is."_  -Bruce Lee
Kalen Michael's avatar
Kalen Michael committed
60
61
62

## Submitting a Bug Report 🐛

Glenn Jocher's avatar
Glenn Jocher committed
63
64
If you spot a problem with YOLOv5 please submit a Bug Report!

Glenn Jocher's avatar
Glenn Jocher committed
65
66
For us to start investigating a possibel problem we need to be able to reproduce it ourselves first. We've created a few
short guidelines below to help users provide what we need in order to get started.
Kalen Michael's avatar
Kalen Michael committed
67

Glenn Jocher's avatar
Glenn Jocher committed
68
69
70
71
When asking a question, people will be better able to provide help if you provide **code** that they can easily
understand and use to **reproduce** the problem. This is referred to by community members as creating
a [minimum reproducible example](https://stackoverflow.com/help/minimal-reproducible-example). Your code that reproduces
the problem should be:
Kalen Michael's avatar
Kalen Michael committed
72
73
74
75
76

***Minimal** – Use as little code as possible that still produces the same problem
***Complete** – Provide **all** parts someone else needs to reproduce your problem in the question itself
***Reproducible** – Test the code you're about to provide to make sure it reproduces the problem

Glenn Jocher's avatar
Glenn Jocher committed
77
78
In addition to the above requirements, for [Ultralytics](https://ultralytics.com/) to provide assistance your code
should be:
Kalen Michael's avatar
Kalen Michael committed
79

Glenn Jocher's avatar
Glenn Jocher committed
80
81
82
83
84
***Current** – Verify that your code is up-to-date with current
  GitHub [master](https://github.com/ultralytics/yolov5/tree/master), and if necessary `git pull` or `git clone` a new
  copy to ensure your problem has not already been resolved by previous commits.
***Unmodified** – Your problem must be reproducible without any modifications to the codebase in this
  repository. [Ultralytics](https://ultralytics.com/) does not provide support for custom code ⚠️.
Kalen Michael's avatar
Kalen Michael committed
85

Glenn Jocher's avatar
Glenn Jocher committed
86
87
88
89
If you believe your problem meets all of the above criteria, please close this issue and raise a new one using the 🐛 **
Bug Report** [template](https://github.com/ultralytics/yolov5/issues/new/choose) and providing
a [minimum reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) to help us better
understand and diagnose your problem.
Kalen Michael's avatar
Kalen Michael committed
90
91
92

## License

Glenn Jocher's avatar
Glenn Jocher committed
93
94
By contributing, you agree that your contributions will be licensed under
the [GPL-3.0 license](https://choosealicense.com/licenses/gpl-3.0/)