Skip to content

Latest commit

 

History

History
117 lines (84 loc) · 5 KB

CONTRIBUTING.md

File metadata and controls

117 lines (84 loc) · 5 KB

Feedback and Contribution

We welcome any input, feedback, bug reports, and contributions via CS Tools's GitHub Repository.

All contributions, suggestions, and feedback you submitted are accepted under the Project's license. You represent that if you do not own copyright in the code that you have the authority to submit it under the Project's license. All feedback, suggestions, or contributions are not confidential.

Setting Up Your Environment

Fork the CS Tools repository on GitHub and then clone the fork to you local machine. For more details on forking see the GitHub Documentation.

git clone https://github.com/YOUR-USERNAME/cs_tools.git

To keep your fork up to date with changes in this repo, you can use the fetch upstream button on GitHub.

CS Tools uses uv (docs) to manage its dependencies. Once you have cloned the repository, run the following command from the root of the repository to setup your development environment:

cd cs_tools/
uv pip install -e ".[dev]"
uv run hatch run dev:setup

Now you can install the latest version of CS Tools locally using pip. The -e flag indicates that your local changes will be reflected every time you open a new Python interpreter (instead of having to reinstall the package each time).

[dev,docs] indicates that pip should also install the development and documentation requirements which you can find in pyproject.toml ([project.optional-dependencies]/dev and [project.optional-dependencies]/docs)

pre-commit install installs the pre-commit hook which will automatically check your code for issues before committing. To run the checks locally, run uv run pre-commit run --all-files.

Creating a Branch

Once your local environment is up-to-date, you can create a new git branch which will contain your contribution (always create a new branch instead of making changes to the main branch):

git switch -c <your-branch-name> dev

With this branch checked-out, make the desired changes to the package.

Creating a Pull Request

When you are happy with your changes, you can commit them to your branch by running

git add <modified-file>
git commit -m "Some descriptive message about your change"
git push origin <your-branch-name>

You will then need to submit a pull request (PR) on GitHub asking to merge your example branch into the main CS Tools repository. For details on creating a PR see GitHub documentation Creating a pull request.

You can add more details about your example in the PR such as motivation for the example or why you thought it would be a good addition. You will get feedback in the PR discussion if anything needs to be changed. To make changes continue to push commits made in your local example branch to origin and they will be automatically shown in the PR.

Hopefully your PR will be answered in a timely manner and your contribution will help others in the future.

How To Contribute Documentation to CS Tools

CS Tools documentation is written in Markdown and compiled into html pages using Material for MkDocs. Contributing to the documentation requires some extra dependencies.

uv pip install -e ".[docs]"

Set your environment variables so that the generated documentation (hooks/cli_reference_generator.py) can be built against a valid ThoughtSpot cluster.

Windows

$env:CS_TOOLS_THOUGHTSPOT__URL = "https://<YOUR-THOUGHTSPOT-CLUSTER>.thoughtspot.cloud"
$env:CS_TOOLS_THOUGHTSPOT__USERNAME = "<YOUR-THOUGHTSPOT-USERNAME>"
$env:CS_TOOLS_THOUGHTSPOT__PASSWORD = "<YOUR-THOUGHTSPOT-PASSWORD>"

POSIX (Mac, Linux)

CS_TOOLS_THOUGHTSPOT__URL = "https://<YOUR-THOUGHTSPOT-CLUSTER>.thoughtspot.cloud"
CS_TOOLS_THOUGHTSPOT__USERNAME = "<YOUR-THOUGHTSPOT-USERNAME>"
CS_TOOLS_THOUGHTSPOT__PASSWORD = "<YOUR-THOUGHTSPOT-PASSWORD>"

Note that the CS Tools website is only updated when a new version is released so your contribution might not show up for a while.

To build the documentation locally, you can use the following commands:

uv run hatch run docs:serve

To view the documentation, open your browser and go to http://localhost:8000. To stop the server, use ^C (control+c) in the terminal.

Important

New commands are automatically documented, as the CLI Reference page is generated from the command line itself.

See docs/hooks/cli_reference_generator.py for implementation details.