From 9206c935172ae215059abffa50f21abaf8cf3626 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Mon, 21 Jan 2019 17:30:28 -0500 Subject: [PATCH] Update documentation Document that we now support GitHub. Also, change .md files to use ~~~~ instead of `...` because that's friendlier to people who want to cut-and-paste commands. Signed-off-by: David A. Wheeler --- CONTRIBUTING.md | 50 +++++++++++++++++++++++++++++++++++++--------- INSTALL.md | 17 ++++++++++++---- README.md | 21 +++++++++++++++++-- release_process.md | 28 +++++++++++++++++++------- 4 files changed, 94 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5218a88..797d0dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,13 +3,24 @@ We love contributions! Here's how to do them in a way that will make everyone's lives easy. +Flawfinder has long been maintained on SourceForge. +We now support reporting and changes using either SourceForge or GitHub. + ## Reporting -For normal problems, bugs, and feature requests, please file a -[ticket](https://sourceforge.net/p/flawfinder/_list/tickets). +For normal problems, bugs, and feature requests, *except* for +vulnerabilities, please file a +[GitHub issue](https://github.com/david-a-wheeler/flawfinder/issues) or +[SourceForge ticket](https://sourceforge.net/p/flawfinder/_list/tickets). If you find a vulnerability, please separately send a private email to [David A. Wheeler](https://dwheeler.com/contactme.html). +To maintain confidentiality, +please use an email system that implements STARTTLS hop-by-hop email +encryption on outgoing email (many do, including +Gmail, hotmail.com, live.com, outlook.com, and runbox.com). +For more about STARTTLS, see the +EFF's [STARTTLS Everywhere](https://www.starttls-everywhere.org/) project. We plan to handle vulnerabilities separately, fixing them and *then* telling the world. We will gladly provide credit to vulnerability reporters (unless you don't want the credit). We've never had a vulnerability @@ -19,9 +30,13 @@ report, so this is theoretical at this time. We use "git" to track changes. To propose a change, create a fork (copy) of the repository, make your changes, and create a -merge request (also called a pull request). +GitHub pull request or SourceForge merge request (they are the same thing). + If you're not familiar with the process, here's some -[documentation](https://sourceforge.net/p/forge/documentation/Git/). +documentation for +[GitHub](https://help.github.com/articles/about-pull-requests/) +and +[SourceForge](https://sourceforge.net/p/forge/documentation/Git/). ## License and DCO @@ -55,15 +70,21 @@ An easy way to install pylint is to use pip. Most python installs have pip, but if yours does not (e.g., Cygwin), install pip with: -`python -m ensurepip` +~~~~ +python -m ensurepip +~~~~ You may want to upgrade pip with: -`pip install --upgrade pip` +~~~~ +pip install --upgrade pip +~~~~ Finally, you can actually install pylint using: -`pip install pylint` +~~~~ +pip install pylint +~~~~ ## Code Conventions @@ -80,12 +101,16 @@ patches to improve that are often welcome. The code must run on both Python 2.7 and Python 3. To check that it works on both, run: -`make check` +~~~~ +make check +~~~~ We use "pylint" to check for style and other generic quality problems. To check that the code passes these quality tests, run: -`make pylint` +~~~~ +make pylint +~~~~ We require that the pylint results for contributions be at least 9.5/10 as configured with the provided "pylintrc" file, without any errors ("E"). @@ -108,5 +133,12 @@ the automated test suite. ## Other +Project documentation tends to be in markdown (.md) format. +We use "~~~~" so that it's easy to cut-and-paste commands if desired. +The main document is a man page, which is then converted to PDF. + +Avoid trailing space or tab on a line in source files - those can create +hard-to-understand "differences" on lines. + We have earned a [CII Best Practices Badge](https://bestpractices.coreinfrastructure.org/projects/323)... make sure we keep it! diff --git a/INSTALL.md b/INSTALL.md index d29009d..5033898 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -12,7 +12,9 @@ For many, the simple approach is to first install Python Then use `pip` to install flawfinder (this will normally download the package): -`pip install flawfinder` +~~~~ +pip install flawfinder +~~~~ One advantage for using pip is that you'll generally get the *current* released version. @@ -28,7 +30,10 @@ For a ports-based system where you have a current port, just use that. This will work out-of-the-box; it may not be the most recent version. One way to accomplish this is: -`sudo apt install flawfinder` + +~~~~ +sudo apt install flawfinder +~~~~ ## 3. TARBALL (SOURCE INSTALL) @@ -37,7 +42,9 @@ QUICK START: The quick way to install flawfinder from the tarball is to unpack the tarball and type in something like this on the command line: -`sudo make prefix=/usr install` +~~~~ +sudo make prefix=/usr install +~~~~ Omit prefix=/usr to install in /usr/local instead. Omit "sudo" if you are already root. @@ -119,4 +126,6 @@ Not enough? Here are more detailed step-by-step instructions and options. You can also simply run the program in the directory you've unpacked it into. It's a simple Python program, just type into a command line: -`./flawfinder files_or_directory` +~~~~ +./flawfinder FILES-OR-DIRECTORY +~~~~ diff --git a/README.md b/README.md index e0c4983..0a3aea8 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ For more information, see the [project website](http://dwheeler.com/flawfinder) Flawfinder is designed for use on Unix/Linux/POSIX systems (including Cygwin, Linux-based systems, MacOS, and various BSDs) as a -command line tool. It requires Python 2.7 or Python 3. +command line tool. It requires either Python 2.7 or Python 3. # Installation @@ -31,7 +31,24 @@ You don't HAVE to install it to run it, but it's easiest that way. To run flawfinder, just give it a list of source files or directories to example. For example, to examine all files in "src/" and down recursively: -`flawfinder src/` +~~~~ +flawfinder src/ +~~~~ + +To examine all files in the *current* directory and down recursively: + +~~~~ +flawfinder ./ +~~~~ + +Hits (findings) are given a risk level from 0 (very low risk) to 5 (high risk), +By default, findings of risk level 1 or higher are shown. +You can show only the hits of risk level 4 or higher in the current +directory and down this way: + +~~~~ +flawfinder --minlevel 4 ./ +~~~~ The manual page (flawfinder.1 or flawfinder.pdf) describes how to use flawfinder (including its various options) and related information diff --git a/release_process.md b/release_process.md index 12646af..38faacc 100644 --- a/release_process.md +++ b/release_process.md @@ -15,23 +15,33 @@ setup.py index.html Then run: -`make test && make test-is-correct` # update version number in tests + +~~~~ +make test && make test-is-correct # update version number in tests +~~~~ ## Test it -`make check` # Run tests in Python 2 and 3 +~~~~ +make check # Run tests in Python 2 and 3 +~~~~ ## Tag version Once you're sure this is the *real* version, tag it: -`git tag VERSION` -`git push --tags` +~~~~ +git tag VERSION +git push --tags +~~~~ ## Create tarball Run: -`make distribute` + +~~~~ +make distribute +~~~~ ## Post tarball @@ -46,8 +56,12 @@ the usual places: Create a PyPi distribution package: -`make pypi` +~~~~ +make pypi +~~~~ And upload it: -`make upload-pypi` +~~~~ +make upload-pypi +~~~~