diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c28ee448e5f..f96879d9fb2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,22 +25,66 @@ commits](https://help.github.com/articles/signing-commits-with-gpg/). ## Sending Data about CVE Entries to MITRE -0. If you haven't done so already, fork the _cvelist_ repository. +0. If you haven't done so already, create an account on Github.com +and fork the _cvelist_ repository. For example, if your account name +is `$YOU`, this will result in a new repo named $YOU/cvelist. +[**NB**: `$YOU` is used throughout the rest of this file; substitute +your own account name in any names, commands, URLs, etc.] Then clone +your repo on a local host, such as your workstation or a *nix +system where you have shell access. -1. Ensure your [fork is up to date](https://help.github.com/articles/syncing-a-fork/), -especially prior to creating a new branch (every time you create a new branch). +1. Ensure your [fork is up to +date](https://help.github.com/articles/syncing-a-fork/), especially +prior to creating a new branch (every time you create a new branch). -2. Create a new branch. We recommend grouping related updates into a -single submission and using a separate branch for each submission. -For example, one CNA may choose to have a single submission for each -monthly patch bundle, while another may opt for a daily submission. +2. Optionally push any updates from the upstream `CVEProject/cvelist` +master back to Github.com (eg, `git push`). -3. Make changes to one or more files. **NB:** limit your changes to +2. Create a new branch, separate from `master`, for each submission. +We encourage you to include in that multiple, related updates whenever +possible. For example, if you publish monthly advisories, you might +name your branch `Nov-2017` and use that to send us assignment +information for all the CVE ids you assigned in that month. If +instead you publish advisories only as needed, you might name your +branch using the advisory id (eg, `SA-2017-11-03`) and include in +that assignment information for the CVE ids you assigned for only +this one advisory. For now, let's assume you've named your branch +`$YOUR_BRANCH` (eg, `git checkout -b $YOUR_BRANCH`). + +3. Make changes to one or more files. **NB:** limit your changes to only those portions of the JSON that need to be updated rather than naively overwriting the entire file. -4. Create a pull request to merge the changes in your new branch into -the cvelist master. +4. Validate any files you change against the JSON schema and +ensure they pass. + +5. **Review your updates carefully** and make sure they contain +**only information you intend to make public**. Once those reach +Github.com, it' extremely difficult if not impossible to put it back +under wraps. For example, you may be able to check that every CVE id +is mentioned in one of the references associated with it to avoid +making public information about a vulnerability ahead of schedule. +Also, review the details in the description. Do they agree with +information in the associated references? + +6. Commit your changes (eg, `git commit -av`) and, if necessary, push +your branch from your local copy of your repo to Github.com (eg, `git +push origin $YOUR_BRANCH`). + +7. Create a pull request to merge the changes in your new branch into +`CVEProject/cvelist` master. You can do this by browsing to +https://github.com/$YOU/cvelist/pull/new/master and then filling in +the form. There are several fields that you need to worry about : + +* `base fork` is the upstream repo in which you want your updates merged - `CVEProject/cvelist` +* `base` is the branch in the upstream repo in which the changes should be placed - `master` +* `head fork` is your repo from which the updates should be taken; eg, `$YOU/cvelist` +* `compare` is the branch in your repo where the changes are; eg, `$YOUR_BRANCH` + +If you created your pull request using the URL above, make sure that +Github reports that the branches can be merged. If not, say because +you forgot to ensure your fork was synched with the upstream master, +make additional commits in your branch to resolve the merge conflicts. After a pull request has been submitted, the CVE Team will review the submission and work with you to resolve issues. Then the CVE Team @@ -60,10 +104,10 @@ github.com/CVEProject/cvelist --> fork --> github.com/$YOU/cvelist | /localpath/repo/cvelist create | pull request | | | git branch git branch - github.com/$YOU/cvelist/cve_assign_20170915 | | + github.com/$YOU/cvelist/$YOUR_BRANCH | | | | V | V some_other_branch - `-- push to your github <-- cve_assign_20170915 + `-- push to your github <-- $YOUR_BRANCH ``` ## Contact