You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The CVE Binary Tool team participates in a few events every year that are aimed at new people in open source. This guide is meant to help people get over the initial hurdle of figuring out how to use git and make a contribution.
5
4
6
5
If you've already contributed to other open source projects, contributing to the CVE Binary Tool project should be pretty similar and you can probably figure it out by guessing. But if you've never contributed to anything before, or you just want to see what we consider best practice before you start, this is the guide for you!
7
6
7
+
## Imposter syndrome disclaimer
8
8
9
+
_We want your help_. No really, we do.
9
10
10
-
Getting and maintaining a local copy of the source code
There might be a little voice inside that tells you you're not ready; that you need to do one more tutorial, or learn another framework, or write a few more blog posts before you can help with this project.
12
+
13
+
I assure you, that's not the case.
14
+
15
+
This document contains some contribution guidelines and best practices, but if you don't get it right the first time we'll try to help you fix it.
16
+
17
+
The contribution guidelines outline the process that you'll need to follow to get a patch merged. By making expectations and process explicit, we hope it will make it easier for you to contribute.
18
+
19
+
And you don't just have to write code. You can help out by writing documentation, tests, or even by giving feedback about this work. (And yes, that includes giving feedback about the contribution guidelines.)
20
+
21
+
If have questions or want to chat, we have a [gitter chat room](https://gitter.im/cve-bin-tool/community) where you can ask questions, or you can put them in [GitHub issues](dhttps://github.com/intel/cve-bin-tool/issues) too.
22
+
23
+
Thank you for contributing!
24
+
25
+
This section is adapted from [this excellent document from @adriennefriend](https://github.com/adriennefriend/imposter-syndrome-disclaimer)
26
+
27
+
## Getting and maintaining a local copy of the source code
12
28
13
29
There are lots of different ways to use git, and it's so easy to get into a messy state that [there's a comic about it](https://xkcd.com/1597/). So... if you get stuck, remember, even experienced programmers sometimes just delete their trees and copy over the stuff they want manually.
14
30
@@ -20,26 +36,142 @@ Once you've got the copy, you can update it using
20
36
21
37
`git pull`
22
38
23
-
Git allows you to have "branches" with variant versions of the code. You can see what's available using `git branch` and switch to one using `git checkout branch_name`.
39
+
You're also going to want to have your own "fork" of the repository on GitHub.
40
+
To make a fork on GitHub, read the instructions at [Fork a
This section isn't required, but many contributors find it helpful, especially for running tests using different versions of python.
54
+
55
+
[virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool for setting up virtual python environments. This allows you to have all the dependencies for cve-binary-tool set up in a single environment, or have different environments set up for testing using different versions of Python.
56
+
57
+
To install it:
58
+
59
+
```bash
60
+
pip install vitualenv
61
+
```
62
+
63
+
To make a new venv using python 3.8:
64
+
65
+
```bash
66
+
virtualenv -p python3.8 ~/Code/venv3.8
67
+
```
68
+
69
+
Each time you want to use a virtualenv, you "activate" it using the activate script:
70
+
71
+
```bash
72
+
source~/Code/venv3.8/bin/activate
73
+
```
74
+
75
+
And when you're done with the venv, you can deactivate it using the `deactivate` command.
76
+
77
+
While you're in a venv, the `python` command will point to whatever version you specified when the venv was created, and pip command will install things only in that venv so you don't have to worry about conflicts with other versions or system packages.
78
+
79
+
## Installing dependencies
80
+
81
+
The packages you need to run CVE Binary Tool are listed in the `requirements.txt` file in the main cve-bin-tool directory. You can install all of them using the following pip command.
24
82
25
-
To make your life easier, we recommend that the `master` branch always be kept in sync with the repo at `https://github.com/intel/cve-bin-tool`, as in you never check in any code to that branch.
83
+
```bash
84
+
pip install -r requirements.txt
85
+
```
86
+
87
+
## Running tests
88
+
89
+
The CVE Binary Tool has a set of tests that can be run using `pytest` command. Usually all the short tests should pass, although sometimes internet connectivity issues will cause problems.
90
+
91
+
[There is a README file in the tests directory](https://github.com/intel/cve-bin-tool/blob/master/test/README.md) which contains more info about how to run just specific tests, or how to run the longer tests which involve downloading full software packages to test the tool. The long tests sometimes fail due to package name changes, which may not be your fault unless you modified one of them.
26
92
93
+
## Running Black
27
94
28
-
Setting up your personal fork
29
-
-----------------------------
95
+
CVE Binary Tool uses Black as the style formatter. Contributors are requested
96
+
to format their code with Black before submitting, and the CI will warn you if your
97
+
code needs re-formatting.
30
98
31
-
To make a fork on github, read the instructions at [Fork a repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
99
+
Black can be installed using pip.
32
100
101
+
```bash
102
+
pip install black
103
+
```
104
+
105
+
To format the code, you run `black` followed by the filename you wish to reformat. For formatting a particular file name filename.py.
106
+
107
+
```bash
108
+
black filename.py
109
+
```
110
+
111
+
In many cases, it will make your life easier if you only run black on
112
+
files you've changed because you won't have to scroll through a pile of
113
+
auto-formatting changes to find your own modifications. However, you can also
114
+
specify a whole folder using ```./```
115
+
116
+
### Using pre-commit to run Black
117
+
118
+
We've provided a pre-commit hook (in `.pre-commit.config.yaml`) so if you want
119
+
to run Black locally before you commit, you can install pre-commit and install
120
+
the hook as follows from the main cve-bin-tool directory:
121
+
122
+
```bash
123
+
pip install pre-commit
124
+
pre-commit install
125
+
```
126
+
127
+
## Making a new branch & pull request
128
+
129
+
Git allows you to have "branches" with variant versions of the code. You can see what's available using `git branch` and switch to one using `git checkout branch_name`.
130
+
131
+
To make your life easier, we recommend that the `master` branch always be kept in sync with the repo at `https://github.com/intel/cve-bin-tool`, as in you never check in any code to that branch. That way, you can use that "clean" master branch as a basis for each new branch you start as follows:
132
+
133
+
```bash
134
+
git checkout master
135
+
git pull
136
+
git checkout -b my_new_branch
137
+
```
138
+
139
+
When you're ready to share that branch to make a pull request, make sure you've checked in all the files you're working on. You can get a list of the files you modified using `git status` and see what modifications you made using `git diff`
140
+
141
+
Use `git add FILENAME` to add the files you want to put in your pull request, and use `git commit` to check them in. Try to use [a clear commit message](https://chris.beams.io/posts/git-commit/). We usually merge pull requests into a single commit when we accept them, so it's fine if you have lots of commits in your branch while you figure stuff out.
142
+
143
+
Once your branch is ready and you've checked in all your code, push it to your fork:
144
+
145
+
```bash
146
+
git push myfork
147
+
```
148
+
149
+
From there, you can go to [our pull request page](https://github.com/intel/cve-bin-tool/pulls) to make a new pull request from the web interface.
150
+
151
+
## Code Review
152
+
153
+
Once you have created a pull request (PR), GitHub Actions will try to run all the tests on your code. If you can, make any modifications you need to make to ensure that they all pass, but if you get stuck a reviewer will see if they can help you fix them. Remember that you can run the tests locally while you're debugging; you don't have to wait for GitHub to run the tests (see the [Running tests](#running-tests) section above for how to run tests).
154
+
155
+
Someone will review your code and try to provide feedback in the comments on GitHub. Usually it takes a few days, sometimes up to a week. The core contributors for this project work on it as part of their day jobs and are usually on US Pacific time, so you might get an answer a bit faster during their work week.
156
+
157
+
If something needs fixing or we have questions, we'll work back and forth with you to get that sorted. We usually do most of the chatting directly in the pull request comments on GitHub, but if you're stuck you can also stop by our [Gitter chat room](https://gitter.im/cve-bin-tool/community) to talk with folk outside of the bug.
158
+
159
+
Once any issues are resolved, we'll merge your code. Yay!
160
+
161
+
In rare cases, the code won't work for us and we'll let you know. Sometimes this happens because someone else has already submitted a fix for the same bug, (Issues marked [good first issue](https://github.com/intel/cve-bin-tool/labels/good%20first%20issue) can be in high demand!) or because you worked on a checker that didn't have a good signature. Don't worry, these things happens, no one thinks less of you for trying!
33
162
34
163
## Style Guide for cve-bin-tool
164
+
35
165
This list contains all the style guide that one must follow while contributing so that code is consistent and maintainable.
36
166
37
167
### String Formatting
168
+
38
169
Python provides many different ways to format the string(you can read about them [here](https://realpython.com/python-formatted-output/))and we use f-string formatting in our tool.
39
170
40
-
**Note: As f-strings are only supported in python 3.6+. Please make sure you have version >=3.6**
171
+
**Note: As f-strings are only supported in python 3.6+.** Please make sure you have version >=3.6
41
172
42
173
-**Example:** Formatting string using f-string
174
+
43
175
```python
44
176
#Program prints a string containing name and age of person
45
177
name ="John Doe"
@@ -49,26 +181,42 @@ print(f"Name of the person is {name} and his age is {age}")
49
181
#Output
50
182
# "Name of the person is John Doe and his age is 23"
51
183
```
184
+
52
185
Note that the string started with the **'f'** followed by the string. Values are always added in the curly braces. Also we don't need to convert age into string. (we may have used **str(age )** before using it in the string) f-strings are useful as they provide many cool features. You can read more about features and the good practices to use f-strings [here](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python).
53
186
54
-
### Style Format
55
-
CVE Binary Tool uses Black as the style formatter. Contributors are requested to format their code with Black before submitting.
187
+
## Making documentation
188
+
189
+
The documentation for CVE Binary Tool can be found in the `doc/` directory (with the exception of the README.md file, which is stored in the main directory but linked in the documentation directory for convenience).
190
+
191
+
Like many other Python-based projects, CVE Binary Tool uses Sphinx and
192
+
ReadTheDocs to format and display documentation. If you're doing more than minor typo
193
+
fixes, you may want to install the relevant tools to build the docs. There's a
194
+
`requirements.txt` file available in the `doc/` directory you can use to install
195
+
sphinx and related tools:
56
196
57
-
#### Installing Black
58
-
Black can be easily installed with the help of pip.
59
197
```bash
60
-
$ pip install black
61
-
```
198
+
cd doc/
199
+
pip install -r requirements.txt
200
+
```
201
+
202
+
Once those are installed, you can build the documentation using `make` in the
203
+
docs directory:
62
204
63
-
#### Formatting Code
64
-
Formatting a file is easy. Just navigate to the file and run the following command. For formatting a particular file name filename.py.
65
205
```bash
66
-
$ black filename.py
206
+
make docs
67
207
```
68
-
But in real life you might want to format each file in a particular folder.
208
+
209
+
or use sphinx-build directly with the following options:
210
+
69
211
```bash
70
-
$ cd Code/
71
-
$ black ./
212
+
sphinx-build -b html . _build
72
213
```
73
-
In my case the name of the folder is Code. First navigate to the folder and then use black on the folder using ```./```
74
214
215
+
That will build the HTML rendering of the documentation and store it in the
216
+
`_build` directory. You can then use your web browser to go to that
217
+
directory and see what it looks like.
218
+
219
+
Note that you don't need to commit anything in the `_build` directory. Only the `.md` and `.rst` files should be checked in to the repository.
220
+
221
+
If you don't already have an editor that understands Markdown (`.md`) and
222
+
RestructuredText (.`rst`) files, you may want to try out Visual Studio Code, which is free and has a nice Markdown editor with a preview.
0 commit comments