From e596011638558991090420fdab960c839f474b37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edgar=20Rami=CC=81rez=20Mondrago=CC=81n?= Date: Mon, 20 Jun 2022 22:16:11 -0500 Subject: [PATCH] docs: Update contributing docs --- .github/workflows/test.yml | 2 +- CONTRIBUTING.md | 41 ----------- docs/CONTRIBUTING.md | 136 ++++++++++++++++++++++++------------- tox.ini | 17 ++++- 4 files changed, 105 insertions(+), 91 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c2b65f61d4..b2ab35cb9f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -151,7 +151,7 @@ jobs: - name: Create coverage report run: | - poetry run tox -e coverage_xml + poetry run tox -e coverage_artifact -- xml - name: Upload coverage report uses: codecov/codecov-action@v3.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 437defb7a1..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,41 +0,0 @@ -# Contributing - -Let's build together! Please see our [Contributor Guide](https://docs.meltano.com/contribute/) -for more information on contributing to Meltano. - -We believe that everyone can contribute and we welcome all contributions. -If you're not sure what to work on, here are some [ideas to get you started](https://github.com/meltano/meltano/labels/Accepting%20Merge%20Requests). - -Chat with us in [#contributing](https://meltano.slack.com/archives/C013Z450LCD) on [Slack](https://meltano.com/slack). - -Contributors are expected to follow our [Code of Conduct](https://docs.meltano.com/contribute/#code-of-conduct). - -## Semantic Pull Requests - -This repo uses the [semantic-prs](https://github.com/Ezard/semantic-prs) GitHub app to check all PRs againts the conventional commit syntax. - -Pull requests should be named according to the conventional commit syntax to streamline changelog and release notes management. We encourage (but do not require) the use of conventional commits in commit messages as well. - -In general, PR titles should follow the format ": ", where type is any one of these: - -- `ci` -- `chore` -- `build` -- `docs` -- `feat` -- `fix` -- `perf` -- `refactor` -- `revert` -- `style` -- `test` - -Optionally, you may use the expanded syntax to specify a scope in the form `(): `. Currently scopes are: - - scopes: - - `taps` # tap SDK only - - `targets` # target SDK only - - `mappers` # mappers only - - `templates` # cookiecutters - -More advanced rules and settings can be found within the file `.github/semantic.yml`. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a72e45bb99..b0bc5589ec 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,14 +2,34 @@ _**Note:** The SDK currently works with Python versions 3.7 through 3.10.x. Python 3.6 is no longer supported._ +Let's build together! Please see our [Contributor Guide](https://docs.meltano.com/contribute/) +for more information on contributing to Meltano. + +We believe that everyone can contribute and we welcome all contributions. +If you're not sure what to work on, here are some [ideas to get you started](https://github.com/meltano/sdk/labels/accepting%20pull%20requests). + +Chat with us in [#contributing](https://meltano.slack.com/archives/C013Z450LCD) on [Slack](https://meltano.com/slack). + +Contributors are expected to follow our [Code of Conduct](https://docs.meltano.com/contribute/#code-of-conduct). + ## Setting up Prereqs -If poetry and pipx are not already installed: +Make sure [`poetry`](https://python-poetry.org/docs/), +[`pre-commit`](https://pre-commit.com/) and [`tox`](https://tox.wiki/en/latest/) +are installed. You can use [`pipx`](https://pypa.github.io/pipx/) to install +all of them. To install `pipx`: ```bash pip3 install pipx pipx ensurepath +``` + +With `pipx` installed, you globally add the required tools: + +```bash pipx install poetry +pipx install pre-commit +pipx install tox ``` Now you can use Poetry to install package dependencies: @@ -29,85 +49,107 @@ poetry install --no-root First clone, then... -1. If you are using VS Code, make sure you have also installed the `Python` extension. -2. Ensure you have the correct test library, formatters, and linters installed: +1. Ensure you have the correct test library, formatters, and linters installed: - `poetry install` -3. Configure Linting and Formatting Settings: - - We use `pytest` for testing (`poetry run pytest`). - - We use `black`, `flake8`, `mypy`, and `pydocstyle` as CI linting tests. - - We use `coverage` for code coverage metrics. - - The project-wide max line length is `89`. - - The project has pre-commit hooks. Just run `pre-commit install` and the next time - you make a commit, the changes will be linted. -4. Set interpreter to match poetry's virtualenv: - - In VS Code, run `Python: Select interpreter` and select the poetry interpreter. +1. If you are going to update documentation, install the `docs` extras: + - `poetry install -E docs` +1. The project has `pre-commit` hooks. Install them with: + - `pre-commit install` +1. Most development tasks you might need should be covered by `tox` environments. You can use `tox -l` to list all available tasks. +For example: + + - Run unit tests: `tox -e py`. + + We use `coverage` for code coverage metrics. + + - Run pre-commit hooks: `tox -e pre-commit`. + + We use `black`, `flake8`, `isort`, `mypy` and `pyupgrade`. The project-wide max line length is `88`. + + - Build documentation: `tox -e docs` + + We use `sphinx` to build documentation. + +### If you are using VSCode + +1. Make sure you have also installed the `Python` extension. +1. Set interpreter to match poetry's virtualenv: run + `Python: Select interpreter` and select the poetry interpreter. +1. The [pre-commit extension](https://marketplace.visualstudio.com/items?itemName=MarkLarah.pre-commit-vscode) +will allow to run pre-commit hooks on the current file from the VSCode command palette. ## Testing Locally To run tests: ```bash -# Run all tests (external creds required): -poetry run pytest # Run just the core and cookiecutter tests (no external creds required): -poetry run pytest tests/cookiecutters -poetry run pytest tests/core -``` - -To run tests while gathering coverage metrics: +tox -e py -```bash -# Run with all tests (external creds required): -poetry run coverage run -m pytest -# Run with just the core tests (no external creds required): -poetry run coverage run -m pytest tests/core +# Run all tests (external creds required): +tox -e py -- -m "external" ``` -To view the code coverage report: +To gather and display coverage metrics: ```bash -# CLI output -poetry run coverage report - -# Or html output: -poetry run coverage html && open ./htmlcov/index.html +tox -e combine_coverage ``` -To run all tests: +To view the code coverage report in HTML format: ```bash -poetry run tox +tox -e coverage_artifact -- html && open ./htmlcov/index.html ``` ## Testing Updates to Docs -Documentation runs on Sphinx, a using ReadtheDocs style template, and hosting from +Documentation runs on Sphinx, using ReadtheDocs style template, and hosting from ReadtheDocs.org. When a push is detected by readthedocs.org, they automatically rebuild and republish the docs. ReadtheDocs is also version aware, so it retains prior and unreleased versions of the docs for us. -First, make sure your virtual env has all the right tools and versions: - -```bash -poetry install -``` - To build the docs: ```bash -cd docs # Build docs -poetry run make html +tox -e docs + # Open in the local browser: -open _build/html/index.html +open build/index.html ``` -To build missing stubs: +Sphinx will automatically generate class stubs, so be sure to `git add` them. -```bash -cd docs -poetry run sphinx-autogen -o classes *.rst -``` +## Semantic Pull Requests + +This repo uses the [semantic-prs](https://github.com/Ezard/semantic-prs) GitHub app to check all PRs againts the conventional commit syntax. + +Pull requests should be named according to the conventional commit syntax to streamline changelog and release notes management. We encourage (but do not require) the use of conventional commits in commit messages as well. + +In general, PR titles should follow the format ": ", where type is any one of these: + +- `ci` +- `chore` +- `build` +- `docs` +- `feat` +- `fix` +- `perf` +- `refactor` +- `revert` +- `style` +- `test` + +Optionally, you may use the expanded syntax to specify a scope in the form `(): `. Currently scopes are: + + scopes: + - `taps` # tap SDK only + - `targets` # target SDK only + - `mappers` # mappers only + - `templates` # cookiecutters + +More advanced rules and settings can be found within the file [`.github/semantic.yml`](https://github.com/meltano/sdk/blob/main/.github/semantic.yml). ## Workspace Development Strategies for the SDK diff --git a/tox.ini b/tox.ini index 6d6c4ff4cd..f83fe3e0aa 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = test, lint # By default, use current python for pytest and linting +envlist = test, combine_coverage, coverage_artifact, lint, docs, pre-commit # By default, use current python for pytest and linting passenv = TOXENV CI GITLAB_* CODECOV_* TAP_* TARGET_* SAMPLE_* skipsdist=True isolated_build = true @@ -45,12 +45,25 @@ commands = poetry run isort --check singer_sdk tests samples poetry run flake8 singer_sdk tests samples +[testenv:pre-commit] +whitelist_externals = pre-commit +commands_pre = + pre-commit install +commands = + pre-commit run --all + +[testenv:docs] +commands_pre = + poetry install --no-root -E docs +commands = + poetry run sphinx-build docs build -W + [testenv:combine_coverage] commands = poetry run coverage combine poetry run coverage report --show-missing -[testenv:coverage_xml] +[testenv:coverage_artifact] commands = poetry run coverage xml