spaCy/CONTRIBUTING.md

Contribute to spaCy

Following the v1.0 release, it's time to welcome more contributors into the spaCy project and code base 🎉 This page will give you a quick overview of how things are organised and most importantly, how to get involved.

Table of contents

1. Issues and bug reports
2. Contributing to the code base
3. Updating the website
4. Submitting a tutorial
5. Submitting a project to the showcase
6. Code of conduct

Issues and bug reports

First, do a quick search to see if the issue has already been reported. If so, it's often better to just leave a comment on an existing issue, rather than creating a new one.

If you're looking for help with your code, consider posting a question on StackOverflow instead. If you tag it spacy and python, more people will see it and hopefully be able to help.

When opening an issue, use a descriptive title and include your environment (operating system, Python version, spaCy version). Our issue template helps you remember the most important details to include.

We use the following system to tag our issues:

Issue label	Description
bug	Bugs and behaviour differing from documentation
enhancement	Feature requests and improvements
install	Installation problems
performance	Accuracy, speed and memory use problems
tests	Missing or incorrect tests
linux, osx, windows	Issues related to the specific operating systems
pip, conda	Issues related to the specific package managers
duplicate	Duplicates, i.e. issues that have been reported before
help wanted	Requests for contributions

Contributing to the code base

Coming soon.

Conventions for Python

Coming soon.

Conventions for Cython

Coming soon.

Fixing bugs

When fixing a bug, first create an issue if one does not already exist. The description text can be very short – we don't want to make this too bureaucratic. Next, create a test file named test_issue[ISSUE NUMBER].py in the spacy/tests/regression folder.

Test for the bug you're fixing, and make sure the test fails. If the test requires the models to be loaded, mark it with the pytest.mark.models decorator.

Next, add and commit your test file referencing the issue number in the commit message. Finally, fix the bug, make sure your test passes and reference the issue in your commit message.

Updating the website

Our website and docs are implemented in Jade/Pug, and built or served by Harp. Jade/Pug is an extensible templating language with a readable syntax, that compiles to HTML. Here's how to view the site locally:

sudo npm install --global harp
git clone https://github.com/explosion/spaCy
cd website
harp server

The docs can always use another example or more detail, and they should always be up to date and not misleading. To quickly find the correct file to edit, simply click on the "Suggest edits" button at the bottom of a page.

To make it easy to add content components, we use a collection of custom mixins, like +table, +list or +code. For more info and troubleshooting guides, check out the website README.

Resources to get you started

• Guide to static websites with Harp and Jade (ines.io)
• Building a website with modular markup components (mixins) (explosion.ai)
• Jade/Pug documentation (pugjs.org)
• Harp documentation (harpjs.com)

Submitting a tutorial

Did you write a tutorial to help others use spaCy, or did you come across one that should be added to our directory? You can submit it by making a pull request to website/docs/usage/_data.json:

{
    "tutorials": {
        "deep_dives": {
            "Deep Learning with custom pipelines and Keras": {
                "url": "https://explosion.ai/blog/spacy-deep-learning-keras",
                "author": "Matthew Honnibal",
                "tags": [ "keras", "sentiment" ]
            }
        }
    }
}

A few tips

• A suitable tutorial should provide additional content and practical examples that are not covered as such in the docs.
• Make sure to choose the right category – first_steps, deep_dives (tutorials that take a deeper look at specific features) or code (programs and scripts on GitHub etc.).
• Don't go overboard with the tags. Take inspirations from the existing ones and only add tags for features ("sentiment", "pos") or integrations ("jupyter", "keras").
• Double-check the JSON markup and/or use a linter. A wrong or missing comma will (unfortunately) break the site rendering.

Submitting a project to the showcase

Have you built a library, visualizer, demo or product with spaCy, or did you come across one that should be featured in our showcase? You can submit it by making a pull request to website/docs/usage/_data.json:

{
    "showcase": {
        "visualizations": {
            "displaCy": {
                "url": "https://demos.explosion.ai/displacy",
                "author": "Ines Montani",
                "description": "An open-source NLP visualiser for the modern web",
                "image": "displacy.jpg"
            }
        }
    }
}

A few tips

• A suitable third-party library should add substantial functionality, be well-documented and open-source. If it's just a code snippet or script, consider submitting it to the code category of the tutorials section instead.
• A suitable demo should be hosted and accessible online. Open-source code is always a plus.
• For visualizations and products, add an image that clearly shows how it looks – screenshots are ideal.
• The image should be resized to 300x188px, optimised using a tool like ImageOptim and added to website/assets/img/showcase.
• Double-check the JSON markup and/or use a linter. A wrong or missing comma will (unfortunately) break the site rendering.

Code of conduct

spaCy adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.