diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5517493..2547552 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,100 +1,129 @@ -# Contributing - -Contributions are welcome, and they are greatly appreciated\! Every -little bit helps, and credit will always be given. +![drHEADer](assets/img/hero.png) -You can contribute in many ways: +# Contributing -## Types of Contributions +Contributions are welcome and greatly appreciated! Every little bit helps and credit will always be given. You can +contribute in many ways: -### Report Bugs +### Report a bug -Report bugs at . +Report a bug on the [issue tracker](https://github.com/santandersecurityresearch/drheader/issues). -If you are reporting a bug, please include: +Please include in the report: - - Your operating system name and version. - - Any details about your local setup that might be helpful in - troubleshooting. - - Detailed steps to reproduce the bug. +- Your operating system name and version +- Any details about your local setup that might be helpful in troubleshooting +- Detailed steps to reproduce the bug -### Fix Bugs +### Fix a bug -Look through the GitHub issues for bugs. Anything tagged with "bug" and -"help wanted" is open to whoever wants to implement it. +Look through the [bug tracker](https://github.com/santandersecurityresearch/drheader/labels/bug) for open issues. +Anything tagged with `bug` and `help wanted` is open to whoever wants to fix it. -### Implementing Features +### Implement a new feature -Look through the GitHub issues for features. Anything tagged with -"enhancement" and "help wanted" is open to whoever wants to implement -it. +Look through the [issue tracker](https://github.com/santandersecurityresearch/drheader/labels/enhancement) for open +feature requests. Anything tagged with `enhancement` and `help wanted` is open to whoever wants to implement it. -### Write Documentation +### Write documentation -drHEADer core could always use more documentation, whether as part of -the official drHEADer core docs, in docstrings, or even on the web in -blog posts, articles, and such. +drheader documentation can always be enhanced, whether as part of the official drheader docs, in docstrings, or even on +the web such as in blog posts and articles. -### Submit Feedback +### Submit feedback -The best way to send feedback is to file an issue at -. +The best way to send feedback is to open an issue on the +[issue tracker](https://github.com/santandersecurityresearch/drheader/issues). If you are proposing a feature: - - Explain in detail how it would work. - - Keep the scope as narrow as possible, to make it easier to - implement. - - Remember that this is a volunteer-driven project, and that - contributions are welcome :) +- Explain in detail how it would work +- Keep the scope as narrow as possible to make it easier to implement +- Remember that this is a volunteer-driven project, and that contributions are welcome -## Get Started\! +## Get Started! -Ready to contribute? Here's how to set up -drheader for local development. +Ready to contribute? This section walks through how to set up drheader for local development and prepare a pull request. +Any steps that display an input symbols icon ( :symbols: ) require you to insert some user-specific information into the +command before running it. -1. Fork the drheader repo on GitHub. +#### Pre-requisites -2. Clone your fork locally: +drheader is built using Python 3.8 and Poetry. If you already have these installed, skip ahead to step 3. - $ git clone git@github.com:your_name_here/drheader.git +1. Install [Python 3.8+](https://www.python.org/downloads) -3. Install your local copy into a virtualenv. Assuming you have - virtualenvwrapper installed, this is how you set up your fork for - local development: +2. Install [Poetry](https://python-poetry.org/docs/#installation) - $ mkvirtualenv drheader - $ cd drheader/ - $ python setup.py develop +3. Fork drheader into your GitHub account -4. Create a branch for local development: +4. Clone your fork locally :symbols: + ```shell + $ git clone git@github.com:/drheader.git` + ``` - $ git checkout -b name-of-your-bugfix-or-feature +5. Set up a virtual environment in your local repo + ```shell + $ python -m venv venv + ``` - Now you can make your changes locally. +6. Activate the virtual environment using the appropriate activation command from + [here](https://docs.python.org/3/library/venv.html#how-venvs-work) :symbols: + ```shell + $ source venv/bin/activate + ``` -5. When you're done making changes, check that your changes pass flake8 - and the tests, including testing other Python versions with tox: +7. Install the project dependencies into your local environment + ```shell + $ poetry install --all-extras --no-root + ``` - $ tox +8. Create a branch for local development :symbols: + ```shell + $ git checkout -b + ``` - To get tox, just pip install it into your virtualenv. +9. After making your changes, verify that the tests and required checks are passing (see [running tox](#running-tox)) + ```shell + $ tox + ``` -6. Commit your changes and push your branch to GitHub: +10. Commit your changes and push your branch :symbols: + ```shell + $ git add . + $ git commit -m '' + $ git push origin + ``` - $ git add . - $ git commit -m "Your detailed description of your changes." - $ git push origin name-of-your-bugfix-or-feature - -7. Submit a pull request through the GitHub website. +11. Submit a pull request at ## Pull Request Guidelines When submitting a pull request, please ensure that: -1. You submit it to 'develop' branch and there's no conflicts. -2. You check all tests are passing and have created new ones if change not covered in current test suite. -3. You update `README.md` if functionality has been added or modified. If you are creating new classes or methods, please use docstring to document the code. -4. You update `RULES.md` when extending or modifying the way rules can be used, adding documentation and examples for the new/modified feature. -5. Code works for Python >= 3.8 -6. Once PR is submitted, workflow steps are successful (e.g.: Flake8, Bandit, Safety, etc.) +1. The existing tests are passing, and new functionality is adequately covered with new tests +2. The relevant documentation e.g. `README.md`, `RULES.md`, `CLI.md` is updated to reflect new or changed functionality +3. The code works for Python >= 3.8 +4. The pull request is submitted against the `develop` branch with no merge conflicts +5. The pull request pipeline has succeeded + +#### Running tox + +You can use tox to replicate the workflow environment on your local machine prior to submitting a pull request. This +allows you run exactly the same steps that will run in the pipeline, and ensure that the pull request is ready to be +merged. + +```shell +$ tox +``` + +This will do the following: + +- Run the tests against all supported Python versions ** and verify that test coverage is at least 80% +- Run a static security scan +- Run all required linters +- Verify that `poetry.lock` is up-to-date + +** When testing against a specific Python version, tox expects an interpreter that satisfies the version requirement to +be installed already and visible to tox. If it cannot find a suitable interpreter, the environment will be skipped. To +efficiently manage multiple Python versions, you can use [pyenv](https://github.com/pyenv/pyenv). diff --git a/README.md b/README.md index 6a7e5a8..427f2c4 100644 --- a/README.md +++ b/README.md @@ -13,16 +13,13 @@ drHEADer helps with the audit of security headers received in response to a sing When combined with the OWASP [Application Security Verification Standard](https://github.com/OWASP/ASVS/blob/master/4.0/en/0x22-V14-Config.md) (ASVS) 4.0, it is a useful tool to include as part of an automated CI/CD pipeline which checks for missing HTTP headers. -## How Do I Install It? -drHEADer requires at least Python 3.8 to run. The easiest way to install drHEADer is to clone this repository and via a -terminal window, run the following command: +## Installation +To run drheader, you must have Python 3.8+ installed. The easiest way to install drheader is using pip: ```sh -$ python3 setup.py install --user +$ pip install drheader ``` -This will install all the pre-requisites and you'll end up with a drHEADer executable. - ## How Do I Use It? There are two ways you could use drHEADer, depending on what you want to achieve. The easiest way is using the CLI. diff --git a/RELEASING.md b/RELEASING.md deleted file mode 100644 index dea99c6..0000000 --- a/RELEASING.md +++ /dev/null @@ -1,41 +0,0 @@ -# Releasing - -Our approach to releasing new versions is quite simple. A new version will be released everytime there's a push to master branch. - -We've managed to have all the process to bump version for next release in the different files fully automated by using [GitHub Actions](https://github.com/features/actions). - -We currently have 2 GitHub Actions configured in this repo, which will be triggered when: - -* There's a pull request. - * If the PR is to a non-master branch, this action will run standard checks like pytest, flake8, bandit and safety to ensure everything is good with the code. - * If the PR is to the master branch, this action will run standard checks, automatically bump release version number in appropriate files and commit those changes to the pull request branch. -* There are changes pushed to master branch. - * This action will run standard checks, create the wheel, the release/tag using the version previously bumped and publish the artefact to Pypi - -To bump version in files prior to release, we use [bump2version](https://github.com/c4urself/bump2version). The configuration for it to know what is the current version, what files need to have the version bumped up and what is the next version is in `setup.cfg`. - -```ini -[bumpversion] -current_version = 1.2.2 -commit = True -tag = False -new_version = 2.0.0 - -[bumpversion:file:setup.py] -search = version='{current_version}' -replace = version='{new_version}' - -[bumpversion:file:setup.cfg] -search = current_version = '{current_version}' -replace = current_version = '{new_version}' - -[bumpversion:file:drheader/__init__.py] -search = __version__ = '{current_version}' -replace = __version__ = '{new_version}' - -... -``` - -With this configuration, we are specifying that only those three files need to have the version bumped before release. By default, `bump2version` bumps a minor version (ie . from 1.2.2 to 1.3.0), but if we want it to be a major version or a patch bump, we only need to specify the `new_version` attribute in the configuration with the version we want to use for the release. - -**Note**: Master and develop branches are protected. It means that we require commits to be pushed through pull requests, status checks to pass before merging and restrict who can push to those branches. We aimed to have the release process fully automated, but because issues described [here](https://github.community/t5/GitHub-Actions/How-to-push-to-protected-branches-in-a-GitHub-Action/td-p/29609) or [here](https://github.community/t5/GitHub-Actions/Automatic-version-update-in-protected-branch/m-p/56469#M9895) when using GitHub Actions for this, we decided that disabling this protection in **develop** branch just when a PR from develop to master is submitted would be a good approach for us, so that the action that bumps the versions and commits the changes back can complete successfully.