Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (62 loc) · 6.34 KB

CONTRIBUTING.md

File metadata and controls

102 lines (62 loc) · 6.34 KB
Raw

Contributing to Presidio

🎉 Thanks for taking the time to contribute! 🎉

The following is a set of guidelines for contributing to Presidio.

Code of Conduct

This project has adopted the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to presidio@dataprivacystack.org.

What do I need to know before I get started?

Project Presidio

Presidio is a community project aimed at helping everyone handle their private data and make the world a safer place. Presidio is both a framework and a system. It's a framework in a sense that you could take code parts from it, extend, customize and plug somewhere. It's also a system you could take as a whole or in parts and deploy locally, on-prem on in the cloud. When contributing to presidio, it's important to keep this in mind, as some "framework" contributions might not be suitable for a deployment, or vice-versa.

Rights of contribution

By submitting a contribution, you represent that you have the legal right to contribute the code and that it may be distributed under the project's MIT license. Furthermore, you confirm that you have the right to submit this contribution and that it does not knowingly contain proprietary or confidential information/code.

PR guidelines

Commit message should be clear, explaining the committed changes.

Update CHANGELOG.md:

Under Unreleased section, use the category which is most suitable for your change (changed/removed/deprecated). Document the change with simple readable text and push it as part of the commit. Next release, the change will be documented under the new version.

Getting started with the code

To get started, refer to the documentation for setting up a development environment.

How to test?

For Python, Presidio leverages pytest and ruff. See this tutorial on more information on testing presidio modules.

Code Coverage

PRs require >= 90% coverage on changed lines. A bot will comment on your PR with coverage details.

Adding new recognizers for new PII types

Adding a new recognizer is a great way to improve Presidio. A new capability to detect a new type of PII entity improves Presidio's coverage and makes private data less accessible.

Best practices for developing recognizers are described here. Please follow these guidelines when proposing new recognizers.

Contributing a New Predefined Recognizer

To contribute a new predefined recognizer to Presidio Analyzer:

  1. Choose the correct folder:

    • If your recognizer is specific to a country or region, add it under presidio-analyzer/presidio_analyzer/predefined_recognizers/country_specific/<country>/.
    • For globally applicable recognizers, use generic/.
    • For recognizers based on NLP engines, use nlp_engine_recognizers/.
    • For standalone NER models, use ner/.
    • For third-party integrations, use third_party/.

  2. Add your recognizer class in the appropriate folder.

    • If your recognizer uses regex patterns:
      • Make regex patterns as specific as possible to minimize false positives.
      • Document the source or reference for any new regex logic (e.g., link to a standard, documentation, or example dataset) in the code as a comment.
    • If your recognizer is country-specific (lives under country_specific/<country>/):
      • Declare its country by setting the class-level COUNTRY_CODE = "<iso-3166-1-alpha-2>" attribute (e.g. COUNTRY_CODE = "us" for US recognizers, "de" for Germany). This is what powers RecognizerRegistry.load_predefined_recognizers(countries=[...]). See Filtering recognizers by country for details.
      • The COUNTRY_CODE value should match the directory's country: e.g. anything under country_specific/us/ declares "us", anything under country_specific/de/ declares "de". Use "uk" (not "gb") for the United Kingdom directory to stay consistent with the existing layout.
      • Generic / locale-agnostic recognizers (credit cards, emails, URLs, IBAN, dates, …) leave COUNTRY_CODE unset; the default of None means the recognizer is always loaded regardless of any country filter.

  3. Add your recognizer to the configuration:

    • Add your recognizer to presidio-analyzer/presidio_analyzer/conf/default_recognizers.yaml.
    • For country-specific recognizers, also declare country_code: <iso> on the YAML entry to mirror the class-level COUNTRY_CODE. The loader cross-checks the two and refuses to load on mismatch, so the YAML stays a discoverable record of the country tag for no-code users.
    • For country-specific recognizers, set enabled: false by default in the YAML configuration.

  4. Update imports: Add your recognizer to presidio-analyzer/presidio_analyzer/predefined_recognizers/__init__.py so it is available for import and backward compatibility.

  5. Update __all__: Add your recognizer class name to the __all__ list in the same __init__.py file.

  6. Testing:

    • Ensure all existing tests pass.
    • Add or update tests for your new recognizer.

  7. Documentation:

Fixing Bugs and improving the code

Please review the open issues on Github for known bugs and feature requests. We sometimes add 'good first issue' labels on those we believe are simpler, and 'advanced' labels on those which require more work or multiple changes across the solution.

Adding samples

We would love to see more samples demonstrating how to use Presidio in different scenarios. If you have a sample that you think would be useful for others, please consider contributing it. You can find the samples in the samples folder.

When contributing a sample, make sure it is self contained (e.g. external dependencies are documented), add it [to the index] (docs/samples/index.md), and to the mkdocs.yml file.

Contacting Us

For any questions, please email presidio@dataprivacystack.org.