updated readme and contribution guides

Author: sacca97

CONTRIBUTING.md

@@ -1,65 +1,61 @@
-## How to contribute to project "KB"
+# How to contribute to project KB
 
 ### Developer Certificate of Origin (DCO)
-Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/)
+Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
 
-#### **Do you intend to contribute with new vulnerability data?**
+### **Do you have new vulnerability data?**
 
 A structured process to create and share vulnerability data is work in progress.
 
 Until it is defined, we invite you to just create pull requests in order to
-submit new vulnerability data, using and existing statement as a template. You
+submit new vulnerability data, using an existing statement as a template. You
 should provide, at least the vulnerability identifier, the URL of the source
 code repository of the affected component and one or more identifiers of the
 commits used to fix the vulnerability.
 
-#### **Did you find a bug?**
+### **Did you find a bug?**
 
-* **Ensure the bug was not already reported** by searching on GitHub under
-  [Issues](https://github.com/sap/project-kb/issues).
+* **Ensure the bug was not already reported** by searching in the [GitHub Issues](https://github.com/sap/project-kb/issues).
 
-* If you're unable to find an open issue that addresses the problem, [open a new
-  one](https://github.com/sap/project-kb/issues/new). Be sure to include a
-  **title and clear description**, as much relevant information as possible, and
+* If it is a new one, feel free to [open it](https://github.com/sap/project-kb/issues/new). Be sure to include a
+  **title and a clear description**, as much relevant information as possible, and
   a **code sample** or an **executable test case** demonstrating the expected
   behavior that is not occurring.
 
 
-#### **Did you write a patch that fixes a bug?**
+### **Did you write a patch that fixes a bug?**
 
 * Open a new GitHub pull request with the patch.
-* Ensure the PR description clearly describes the problem and solution. Include
+* Ensure the PR description clearly describes problem and solution. Include
   the relevant issue number if applicable.
-* Add one or more test cases as appropriate
+* Add one or more test cases as appropriate.
 * Make sure all other tests and checks still pass (that is, run `make check` in
   the `kaybee` folder; it should succeed)
 
-#### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
+### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
 
-Changes that are cosmetic in nature and do not add anything substantial to the
-stability, functionality, or testability are accepted at this time.
+Changes that are cosmetic in nature and do not modify the
+stability, functionality, or testability are accepted.
 
-#### **Do you intend to add a new feature or change an existing one?**
+### **Do you intend to add a new feature or change an existing one?**
 
-* Suggest your change by creating an issue  and start writing code in your own
+* Suggest your change by creating an issue, then start writing code in your own
   fork and make a PR when ready. Please make sure you provide tests for your
   code, and ensure you can successfully execute `make check` (in the `kaybee`
   folder) with no errors and that you include adequate documentation in your
   code.
 
 
-
-
-#### **Do you have questions about the source code?**
+### **Do you have questions about the source code?**
 
 * For now, file an issue (we consider that the need of clarifications at this
   stage indicates missing or inadequate documentation).
 
-#### **Do you want to contribute to the documentation?**
+### **Do you want to contribute to the documentation?**
 
-You are most welcome to do so, project "KB" needs every one of you to succeed,
+You are most welcome to do so, project KB needs every one of you to succeed,
 every drop matters!
 
 Thanks! :heart: :heart: :heart:
 
-The project "KB" team
+The project KB team

README.md

@@ -10,7 +10,7 @@
 [![Pytest](https://github.com/SAP/project-kb/actions/workflows/python.yml/badge.svg)](https://github.com/SAP/project-kb/actions/workflows/python.yml)
 
 ## Description
-***
+
 The goal of `Project KB` is to enable the creation, management and aggregation of a
 distributed, collaborative knowledge base of vulnerabilities affecting
 open-source software.
@@ -19,7 +19,7 @@ open-source software.
 as well as set of tools to support the mining, curation and management of such data.
 
 
-### Why this project?
+### Motivations
 
 In order to feed [Eclipse Steady](https://github.com/eclipse/steady/) with fresh
 data, we have spent a considerable amount of time, in the past few years, mining
@@ -50,7 +50,7 @@ other sources.
 
 
 ## Kaybee
-***
+
 Kaybee is a vulnerability data management tool, it makes possible to fetch the vulnerability statements from this
 repository (or from any other repository) and export them to a number of
 formats, including a script to import them to a [Steady
@@ -59,18 +59,18 @@ backend](https://github.com/eclipse/steady).
 For details and usage instructions check out the [kaybee README](https://github.com/SAP/project-kb/tree/main/kaybee).
 
 ## Prospector
-***
+
 Prospector is a vulnerability data mining tool that aims at reducing the effort needed to find security fixes for known vulnerabilities in open source software repositories.
 The tool takes a vulnerability description (in natural language) as input and produces a ranked list of commits, in decreasing order of relevance.
 
 For details and usage instructions check out the [prospector README](https://github.com/SAP/project-kb/tree/main/prospector).
 
 ## Vulnerability data
-***
+
 The vulnerability data of Project KB are stored in textual form as a set of YAML files, in the [vulnerability-data branch](https://github.com/SAP/project-kb/tree/vulnerability-data).
 
 ## Publications
-***
+
 In early 2019, a snapshot of the knowlege base from project "KB" was described in:
 
   - Serena E. Ponta, Henrik Plate, Antonino Sabetta, Michele Bezzi, Cédric
@@ -96,7 +96,6 @@ scripts described in that paper](MSR2019)
 > If you wrote a paper that uses the data or the tools from this repository, please let us know (through an issue) and we'll add it to this list.
 
 ## Credits
-***
 
 ### EU-funded research projects
 
@@ -105,28 +104,22 @@ The development of Project KB is partially supported by the following projects:
 * [AssureMOSS](https://assuremoss.eu) (Grant No.952647).
 * [Sparta](https://www.sparta.eu/) (Grant No.830892).
 
-
 ### Vulnerability data sources
 
 Vulnerability information from NVD and MITRE might have been used as input
 for building parts of this knowledge base. See MITRE's [CVE Usage license](http://cve.mitre.org/about/termsofuse.html) for more information.
 
 ## Limitations and Known Issues
 
-This project is work-in-progress. The vulnerability knowledge base only contains
-information about vulnerabilities in Java and Python open source components.
-
-The list of current issues is available
-[here](https://github.com/SAP/project-kb/issues).
+This project is **work-in-progress**, you can find the list of known issues [here](https://github.com/SAP/project-kb/issues). 
 
-Feel free to open a new issue if you think you found a bug or if you have a feature request.
+Currently the vulnerability knowledge base only contains information about vulnerabilities in Java and Python open source components.
 
-## How to obtain support
+## Support
 
 For the time being, please use [GitHub
-issues](https://github.com/SAP/project-kb/issues) both to report bugs and to
-request help. Documentation and better support channels will come soon.
+issues](https://github.com/SAP/project-kb/issues) to report bugs, request new features and ask for support. 
 
 ## Contributing
 
-See [here](CONTRIBUTING.md).
+See [How to contribute](CONTRIBUTING.md).