From ed2073bf13ce5d566f1657607715f0c7a177c9a1 Mon Sep 17 00:00:00 2001 From: Sharon Hart Date: Tue, 23 Feb 2021 12:57:05 +0200 Subject: [PATCH] Development Documentation (#542) * Development documentation additions * Move development guidelines * Move development guidelines * Move development guidelines * Update docs/development.md Co-authored-by: Nava Vaisman Levy * CR Co-authored-by: sharon Co-authored-by: Nava Vaisman Levy --- CONTRIBUTING.md | 8 ----- docs/development.md | 74 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 70 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a89172f1e..5fc52cd16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,14 +21,6 @@ For more details follow the [Build and Release documentation](docs/build_release To get started, refer to the documentation for [setting up a development environment](docs/development.md). -### General contribution guidelines - -- A Github issue suggesting the change should be opened prior to a PR. -- All contributions should be documented, tested and linted. Please verify that all tests and lint checks pass successfully before proposing a change. -- To make the linting process easier, you can use [pre-commit hooks](docs/development.md#automatically-format-code-and-check-for-code-styling) to verify and automatically format code upon a git commit -- In order for a pull request to be accepted, the CI (containing unit tests, e2e tests and linting) needs to succeed, in addition to approvals from two maintainers. -- PRs should be small and solve/improve one issue at a time. If you have multiple suggestions for improvement, please open multiple PRs. - ### How can I contribute? - [Testing](#how-to-test) diff --git a/docs/development.md b/docs/development.md index f44fc448b..48711d76d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,15 +6,81 @@ ### Cloning the repo -TODO: Describe how to clone, folder structure etc. +To create a local copy of Presidio repository, follow [Github instructions](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) +on how to clone a project using git. +The project is structured so that: +- Each Preisio service has a designated directory. In it, the source code for: + - The service logic. + - Tests, both unit and integration. + - Serving it as an HTTP service (found in app.py). + - Python Packaging setup script (setup.py). +- In the project root directory, you will find common code for using, serving and testing Presidio +as a cluster of services, as well as CI/CD pipelines codebase and documentation. ### Setting up Pipenv -TODO: Add Pipenv documentation from V1. +[Pipenv](https://pipenv.pypa.io/en/latest/) is a Python workflow manager, handling +dependencies and environment for Python packages. It is used by each Presidio service +as the dependencies manager, to be aligned with the specific requirements versions. +Follow these steps when starting to work on a Presidio service with Pipenv: -## Development guidelines +1. Install pipenv -TODO: add description + #### Using Pip3: + + ``` + pip3 install --user pipenv + ``` + + #### Using Homebrew (in MacOS) + + ``` + brew install pipenv + ``` + + Additional installation instructions: https://pipenv.readthedocs.io/en/latest/install/#installing-pipenv + +2. Create virtualenv for the project and install all requirements in the Pipfile, +including dev requirements. For example, in the `presidio-analyzer` folder, run: + + ``` + pipenv install --dev --sequential --skip-lock + ``` + +3. Run all tests + ``` + pipenv run pytest + ``` + +4. To run arbitrary scripts within the virtual env, start the command with +`pipenv run`. For example: + 1. `pipenv run flake8` + 2. `pipenv run pip freeze` + 3. `pipenv run python -m spacy download en_core_web_lg` - To download the +default spacy model needed for Presidio Analyzer. + +#### Alternatively, activate the virtual environment and use the commands by starting a pipenv shell: + +1. Start shell: + + ``` + pipenv shell + ``` + +2. Run commands in the shell + + ``` + pytest + pip freeze + ``` + +### Development guidelines + +- A Github issue suggesting the change should be opened prior to a PR. +- All contributions should be documented, tested and linted. Please verify that all tests and lint checks pass successfully before proposing a change. +- To make the linting process easier, you can use [pre-commit hooks](docs/development.md#automatically-format-code-and-check-for-code-styling) to verify and automatically format code upon a git commit +- In order for a pull request to be accepted, the CI (containing unit tests, e2e tests and linting) needs to succeed, in addition to approvals from two maintainers. +- PRs should be small and solve/improve one issue at a time. If you have multiple suggestions for improvement, please open multiple PRs. ### Local build process