|
| 1 | +# Maintainers Guide |
| 2 | + |
| 3 | +Let's hope to have matching examples of documentation and reference for various runtimes be consistent! |
| 4 | + |
| 5 | +- **[Development](#development)**: Making changes alongside the Node Slack SDK. |
| 6 | +- **[Commands](#commands)**: Reference to running example code of this project. |
| 7 | +- **[Structure](#structure)**: Adding examples for features of the Slack Platform. |
| 8 | + |
| 9 | +## Development |
| 10 | + |
| 11 | +Bringing ongoing changes from the [Python Slack SDK](https://github.com/slackapi/python-slack-sdk) requires building from source with these commands: |
| 12 | + |
| 13 | +```sh |
| 14 | +$ git clone git@github.com:slackapi/python-slack-sdk.git |
| 15 | +$ cd python-slack-sdk |
| 16 | +$ python -m venv .venv |
| 17 | +$ source .venv/bin/activate |
| 18 | +(.venv) $ ./scripts/build_pypi_package.sh |
| 19 | +``` |
| 20 | + |
| 21 | +This bundles a compilation as a `slack_sdk-*-py2.py3-none-any.whl` file that is used to replace previous installations: |
| 22 | + |
| 23 | +```sh |
| 24 | +$ git clone git@github.com:slack-samples/bolt-python-examples.git |
| 25 | +$ cd bolt-python-examples |
| 26 | +$ cd block-kit # Navigate to an example to change |
| 27 | +$ python -m venv .venv |
| 28 | +$ source .venv/bin/activate |
| 29 | +(.venv) $ pip install -r requirements.txt |
| 30 | +(.venv) $ pip install /path/to/python-slack-sdk/dist/slack_sdk-*-py2.py3-none-any.whl --force-reinstall |
| 31 | +``` |
| 32 | + |
| 33 | +## Commands |
| 34 | + |
| 35 | +Each example has matching commands to run tests: |
| 36 | + |
| 37 | +```sh |
| 38 | +$ ruff check |
| 39 | +$ ruff format --diff --check |
| 40 | +$ mypy ./**/*.py |
| 41 | +$ pytest -v |
| 42 | +``` |
| 43 | + |
| 44 | +## Structure |
| 45 | + |
| 46 | +New code snippets or samples added should match the structure of the [docs.slack.dev](https://docs.slack.dev) site: |
| 47 | + |
| 48 | +```txt |
| 49 | +|- .github |
| 50 | + |- dependabot.yml # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-multiple-locations-for-manifest-files |
| 51 | +|- block-kit |
| 52 | + |- blocks # https://docs.slack.dev/reference/block-kit/blocks |
| 53 | + |- formatting # https://docs.slack.dev/block-kit/formatting-with-rich-text |
| 54 | +|- messaging |
| 55 | + |- sending # https://docs.slack.dev/messaging/sending-and-scheduling-messages |
| 56 | + |- work-objects # https://docs.slack.dev/messaging/work-objects |
| 57 | +``` |
| 58 | + |
| 59 | +Some pages might reference distinct examples needing unique app manifests. These should appear in separate nested directories for a minimal demonstration. |
| 60 | + |
| 61 | +Certain features or demonstrations might not have a clear example on the docs site. Discussions with the kind documentation team ought be started if so! We hope folks find relevant examples through those pages. |
| 62 | + |
| 63 | +A goal of this project is to be a source of tested reference. |
0 commit comments