From 980ef6db2475b0e4654e011e448199d38b32449c Mon Sep 17 00:00:00 2001 From: Michael Haas Date: Tue, 15 Dec 2020 16:50:38 +0100 Subject: [PATCH 1/3] Add CONTRIBUTING.md --- CONTRIBUTING.md | 231 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..90831e2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,231 @@ +# How to report an issue + +You can report any issues with the SDK in the +[issues] section on Github. We appreciate your feedback! + +Once you have created the issue, we will try to get back to +you as soon as possible. + +For other concerns, such as questions on the Data Attribute +Recommendation service, please refer to the +["How to obtain support"][support] section in the main README. + +[issues]: https://github.com/SAP/data-attribute-recommendation-python-sdk +[support]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/master/README.md#how-to-obtain-support + +# How to contribute + +This project welcomes outside contributions. For small contributions, such +as corrections of typos, please open a [pull request] on Github with your +change. + +[pull request]: https://github.com/SAP/data-attribute-recommendation-python-sdk/compare + +Once you have created the PR, we will try to get back to +you as soon as possible. + +For larger changes, please open an [issue][issues] first to discuss. We will be happy +to give our feedback on the proposed design! This includes new features, but also +larger refactoring efforts. + +## Tests and Style Checks + +### The short version + +To install pre-commit and run all code checks: + +```shell script +$ pip install -r requirements-dev.txt +$ pre-commit install +$ pre-commit run --all +``` + +See below for details on +[Code Style and Pre-Commit Checks](#code-style-and-pre-commit-checks). + +To run the tests: + +```shell script +$ pip install -r requirements-test.txt +$ tox +``` + +To run the system tests against a live instance of the Data Attribute Recommendation +service, provide the [credentials] as environment variables and run: + +```shell script +$ tox -e system_tests +``` + +See below for more information on [Running Tests](#running-tests). + +## Code Quality + +### Code Style and Pre-Commit Checks + +This project uses the black code formatter for Python. Additionally, we use +several code linting and static analysis tools to ensure that our code base +remains high-quality and maintainable. + +We maintain this collection of checks with [pre-commit]. All the checks are +configured inside of [.pre-commit-config.yaml]. This allows you to check every +change you commit automatically. + +[pre-commit]: https://pre-commit.com/ +[.pre-commit-config.yaml]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/master/.pre-commit-config.yaml + +To set up `pre-commit`, run the following: + +```shell script +$ pip install -r requirements-dev.txt +$ pre-commit install +``` + +Optionally, to verify your installation, you can execute `pre-commit` +manually to check all files: + +```shell script +$ pre-commit run --all +``` + +Now, every time you run `git commit`, the checks will run. If a check fails, +the `git commit` operation is aborted and you can fix the problem. Once the issue +is resolved, you can run `git add` to add your changes to the commit +and try `git commit again`. + +Some checks will automatically fix any issues that they find. The `black` formatter, +for example, will automatically format your changes correctly. For other checks, +you will have to fix the issue manually. Nevertheless, +you still have to commit the updated version explicitly. + +If you experience problems with a single check, you can disable it as follows: + +```shell script +$ SKIP=pylint git commit +``` + +The values for `SKIP` can be taken from the `id` field in [.pre-commit-config.yaml]. + +To disable *all* checks for a commit, use the following: + +```shell script +$ git commit --no-verify +``` + +In general, do not hesitate to submit a PR if the checks fail. We will be happy to +help you resolve any issues. + +## Running tests + +We use [tox] to execute tests. + +[tox]: https://tox.readthedocs.io/en/latest/ + +To install tox, execute the following: + +```shell script +$ pip install -r requirements-test.txt +``` + +To run the unit tests, simply call `tox`: + +```shell script +$ tox +``` + +By default, `tox` will run tests against Python 3.5, 3.6, 3.7 and 3.8. +If you do not have all of these versions installed, you can select only +those versions that you have installed: + +```shell script +$ tox -e py36,py37 +``` + +The unit tests live in the [tests/] directory. + +[tests/]: https://github.com/SAP/data-attribute-recommendation-python-sdk/tree/master/tests + +See our `tox` configuration file at [tox.ini] for details. + +[tox.ini]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/master/tox.ini + +### System Tests + +The system tests are a separate set of tests which run and end-to-end scenario against +a real instance of the Data Attribute Recommendation service. The system tests +live in [system_tests/]. + +[system_tests/]: https://github.com/SAP/data-attribute-recommendation-python-sdk/tree/master/system_tests + +To run the system tests locally, you will need to supply the [credentials as +environment variables][credentials]. However, it is often sufficient to run just the +unit tests, which is much faster. + +To execute the system tests, invoke `tox` with the corresponding environment: + +```shell script +$ tox -e system_tests +``` + +It is not required to run the system tests before submitting your PR. The system tests +are executed by the [Travis CI] system once your PR is merged. + +[credentials]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/f3883f2b56efefb704b0af58811261b4cb6d9b87/system_tests/conftest.py#L17 + +### Checks on Pull Requests + +The checks above - both code quality and unit tests - are run automatically +for every PR on [Travis CI]. See our [travis configuration] for details. + +For security reasons, the system tests are not executed from forked repositories. +Users with write access to the main repository will typically create PRs directly from +the main repository, in which case the system tests actually run also for PRs. + +[Travis CI]: https://travis-ci.com/github/SAP/data-attribute-recommendation-python-sdk +[travis configuration]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/master/.travis.yml + +This setup is a great safety net: all your proposed changes will be automatically +checked to make sure no regression is introduced. + +### Tests and Code Coverage + +We require that meaningful tests are added along each new feature. + +Tests are implemented with [pytest]. + +[pytest]: https://docs.pytest.org/en/stable/ + +We aim not to reduce test coverage. We currently have over 96% test coverage +and we have a check which fails the test if the coverage falls +below this threshold (see [tox.ini]). + +If you get a message similar to the following: + +``` +FAIL Required test coverage of 96% not reached. Total coverage: 92.54% +``` + +Then it is likely you added code without adding sufficient tests. If you don't know +how to add tests, please open a PR with your code and we will be happy to assist. + +### Traceability + +As stated above, we like to have tests that show that our project +- including new features - works correctly. For every release, we generate +a Test Evaluation Report which shows the features delivered and the successful +execution of tests covering this feature. + +If you add a new feature, we'd like to ask that you link the Github issue to +the (system) tests covering this feature. The Test Evaluation Report of the next +release will then include both the feature and its test. + +Please see the documentation we have on the [maintenance of Test Evaluation Reports]. + +[maintenance of Test Evaluation Reports]: https://data-attribute-recommendation-python-sdk.readthedocs.io/en/latest/traceability.html + +## Developer Certificate of Origin (DCO) + +Due to legal reasons, contributors will be asked to accept a DCO before they submit +the first pull request to this projects, this happens in an automated fashion during +the submission process. SAP uses +[the standard DCO text of the Linux Foundation](https://developercertificate.org/). \ No newline at end of file From 2c9dc10aacf46b865f98668ee38c4fe0a4ffc920 Mon Sep 17 00:00:00 2001 From: Michael Haas Date: Tue, 15 Dec 2020 16:51:54 +0100 Subject: [PATCH 2/3] Add CII Best Practices badge --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 87364f2..1ceba82 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Part of [SAP AI Business Services]. [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/) [![REUSE status](https://api.reuse.software/badge/github.com/SAP/data-attribute-recommendation-python-sdk)](https://api.reuse.software/info/github.com/SAP/data-attribute-recommendation-python-sdk) +[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4514/badge)](https://bestpractices.coreinfrastructure.org/projects/4514) Goals of this SDK: From c3dfebbd643c26d2bd15a573232820e16ecd23b9 Mon Sep 17 00:00:00 2001 From: Michael Haas Date: Tue, 15 Dec 2020 17:33:24 +0100 Subject: [PATCH 3/3] Add SECURITY.md --- CONTRIBUTING.md | 4 +++- SECURITY.md | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90831e2..0ec4371 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,9 +10,11 @@ For other concerns, such as questions on the Data Attribute Recommendation service, please refer to the ["How to obtain support"][support] section in the main README. +If you would like to report a security issue, please see [SECURITY.md]. + [issues]: https://github.com/SAP/data-attribute-recommendation-python-sdk [support]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/master/README.md#how-to-obtain-support - +[SECURITY.md]: https://github.com/SAP/data-attribute-recommendation-python-sdk/blob/master/SECURITY.md # How to contribute This project welcomes outside contributions. For small contributions, such diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..c7ae4e3 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,10 @@ +# Security Policy + +If you would like to report a security issue with this +project, please reach out **privately** to michael.haas AT sap DOT com +and evgeny.arnautov AT sap DOT com. We will get back to you soon. + +If you are looking for the security guide, please see the +[project documentation][security guide]. + +[security guide]: https://data-attribute-recommendation-python-sdk.readthedocs.io/en/latest/security.html \ No newline at end of file