From 64e6a80096732e0bf758556235a7ca6b309856a8 Mon Sep 17 00:00:00 2001
From: William Bergamin <william.bergamin.coen@gmail.com>
Date: Mon, 13 Jun 2022 17:21:17 -0400
Subject: [PATCH] Updated maintainer_guide (#1225)

* Updated maintainer_guide to recommend using bash scripts over python scripts
* Added improvements based on feedback
---
 .github/maintainers_guide.md | 50 ++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md
index c1d1f8bef..69721b658 100644
--- a/.github/maintainers_guide.md
+++ b/.github/maintainers_guide.md
@@ -40,7 +40,7 @@ $ pyenv rehash
 
 Then, you can create a new [Virtual Environment](https://docs.python.org/3/tutorial/venv.html) specific to the Python version you just installed by running:
 
-```
+```bash
 $ python -m venv env_3.9.6
 $ source env_3.9.6/bin/activate
 ```
@@ -53,22 +53,33 @@ do so after you are done working in this project. To come back to development
 work for this project again in the future, `cd` into this project directory and
 run `source env_3.9.6/bin/activate` again.
 
-The last step is to install this project's dependencies; to do so, check out [how
-we configure GitHub Actions to install dependencies for this project for use in
-our continuous integration](https://github.com/slackapi/python-slack-sdk/blob/main/.github/workflows/ci-build.yml#L26-L30). You can also run `./scripts/run_validation.sh` to install the dependencies and run the unit tests in one command!
+The last step is to install this project's dependencies and run all unit tests; to do so, you can run
+```bash
+$ ./scripts/run_validation.sh 
+```
 
+Also check out [how
+we configure GitHub Actions to install dependencies for this project for use in
+our continuous integration](https://github.com/slackapi/python-slack-sdk/blob/v3.17.0/.github/workflows/ci-build.yml#L28-L32).
 ## Tasks
 
 ### Testing (Unit Tests)
 
-When you make changes to this SDK, please write unit tests verifying if the changes work as you expected. You can easily run all the tests by running the command. The `validate` command runs Flake8 (static code analyzer), Black (code formatter), and unit tests in the `tests` directory for you.
+When you make changes to this SDK, please write unit tests verifying if the changes work as you expected. You can easily run all the tests and formatting/linter with the below scripts.
+
+Run all the unit tests, code formatter, and code analyzer:
+```bash
+$ ./scripts/run_validation.sh 
+```
 
+Run all the unit tests (no formatter nor code analyzer):
 ```bash
-python setup.py validate # run all
+$ ./scripts/run_unit_tests.sh
+```
 
-# run a single test
-python setup.py validate \
-  --test-target tests/web/test_web_client.py
+Run a specific unit test:
+```bash
+$ ./scripts/run_unit_tests.sh tests/web/test_web_client.py
 ```
 
 You can rely on GitHub Actions builds for running the tests on a variety of Python runtimes.
@@ -77,12 +88,14 @@ You can rely on GitHub Actions builds for running the tests on a variety of Pyth
 
 This project also has integration tests that verify the SDK works with the Slack API platform. As a preparation, you need to set [the required env variables](https://github.com/slackapi/python-slack-sdk/blob/main/integration_tests/env_variable_names.py) properly. You don't need to setup all of them if you just want to run some of the tests. Commonly, `SLACK_SDK_TEST_BOT_TOKEN` and `SLACK_SDK_TEST_USER_TOKEN` are used for running `WebClient` tests.
 
+Run all integration tests:
 ```bash
-python setup.py integration_tests # run all
+$ ./scripts/run_integration_tests.sh
+```
 
-# run a single test
-python setup.py integration_tests \
-  --test-target integration_tests/web/test_web_client.py
+Run a specific integration test:
+```bash
+$ ./scripts/run_integration_tests.sh integration_tests/web/test_async_web_client.py
 ```
 
 ### Generating Documentation
@@ -90,7 +103,16 @@ python setup.py integration_tests \
 The documentation is generated from the source and templates in the `docs-src` directory. The generated documentation
 gets committed to the repo in `docs` and also published to a GitHub Pages website.
 
-You can generate the documentation by running `./scripts/docs.sh`.
+You can generate and preview the **SDK document pages** by running
+```bash
+$ ./scripts/docs.sh
+$ open docs/index.html
+```
+
+Similarly you can generate and preview the **API documents for `slack_sdk` package modules** by running
+```bash
+$ ./scripts/generate_api_docs.sh
+```
 
 ### Releasing