Bleach development¶

Install for development¶

To install Bleach to make changes to it:

Clone the repo from GitHub:

$ git clone git://github.com/mozilla/bleach.git

Create and activate a virtual environment.
Install Bleach and developer requirements into the virtual environment:
```
$ pip install -r requirements-dev.txt
```

Code of conduct¶

This project has a code of conduct.

Reporting Bugs¶

For regular bugs, please report them in our issue tracker.

Reporting security bugs¶

If you believe that you’ve found a security vulnerability, please file a secure bug report in our bug tracker or send an email to security AT mozilla DOT org.

For more information on security-related bug disclosure and the PGP key to use for sending encrypted mail or to verify responses received from that address, please read our wiki page at https://www.mozilla.org/en-US/security/#For_Developers.

Docs¶

Docs are in docs/. We use Sphinx. Docs are pushed to ReadTheDocs via a GitHub webhook.

Testing¶

Run:

$ tox

That’ll run Bleach tests in all the supported Python environments. Note that you need the necessary Python binaries for them all to be tested.

Tests are run as GitHub actions for test and pull request events.

Release process¶

Checkout main tip.
Check to make sure setup.py is correct and match requirements-wise.
Update version numbers in bleach/__init__.py.
1. Set __version__ to something like 2.0.0. Use semver. Bump the minor version if a vendored library was unvendored or updated.
2. Set __releasedate__ to something like 20120731.
Update CONTRIBUTORS, CHANGES, MANIFEST.in and SECURITY.md as necessary.
Verify correctness.
1. Run linting, tests, and everything else with tox:
```
$ tox
```
2. Build the docs:
```
$ cd docs
$ make html
```
3. Run the doctests:
```
$ cd docs/
$ make doctest
```
4. Verify the local vendored files (the second invocation should not exit with /tmp/vendor-test exists. Please remove. and the exit code should be zero):
```
$ make vendorverify
```
5. Run any additional tests to verify everything else works
Commit the changes.
Push the changes to GitHub. This will cause Github Actions to run the tests.
After CI passes, create a signed tag for the release:
```
$ git tag -s v0.4.0
```
Copy the details from CHANGES into the tag comment.
Generate distribution files:
```
$ python -m build
```

Sanity check the release contents and sizes:

$ ls -lh dist/* # file sizes should be similar
$ tar tvzf dist/bleach-${VERSION}.tar.gz
$ unzip -v dist/bleach-${VERSION}-py2.py3-none-any.whl

Using a PyPI API token, upload dist files to PyPI:
```
$ twine upload -r [REPO] dist/*
```
Push the new tag:
```
$ git push --tags [REMOTE] main
```
That will push the release to PyPI.
Blog posts, twitter, etc.