First off, thanks for considering to contribute to this project!
These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
This project adheres to Semantic Versioning.
The CHANGELOG format tries to complies with Keep a Changelog but it's mainly a concatenation of autogenerated release notes by GitHub Release.
We use git hooks through pre-commit to enforce and automatically check some "rules". Please install it before any commit: pre-commit install.
See the relevant configuration file: .pre-commit-config.yaml.
Make sure your code roughly follows PEP-8 and keeps things consistent with the rest of the code:
- docstrings: google-style is used to write technical documentation right into the code.
- formatting: black is used to automatically format the code without debate.
- sorted imports: isort is used to sort imports
- static analisis: flake8 is used to catch some dizziness and keep the source code healthy.
We follow Conventional Commits: <type>(<scope>): <description>, e.g. feat(gui): add Publish tab for uData catalog publication. The scope is optional.
Common types used in this project:
feat: new feature or enhancementfix: bug fixdocs: documentation onlytest: adding or fixing testsrefactor: code change that neither fixes a bug nor adds a featurechore: maintenance (dependency bumps, housekeeping, etc.)ci: CI/CD configurationbuild: build system or packaging
If you used an AI/LLM (Claude, ChatGPT, Copilot, etc.) to help produce a contribution, please disclose it, following the transparency levels described in VisiData's "Using AI to Contribute to Open Source". In your PR description (or as commit message trailers), indicate:
- the disclosure level, per the scale from the article above;
- the model used (name/version);
- a link to the session (chat/agent conversation) that produced the change, when available.
Whatever the level, a human must still vouch for the PR: you should have reviewed and tested the change yourself.
The scale, summarized:
| Level | Name |
|---|---|
| 0 | Human did not use AI at all |
| 1 | Human asked chatbot for ideas |
| 2 | Human coded with minor assists |
| 3 | Human coded, bots assisted non-trivially |
| 4 | Human coded, bots helped significantly |
| 5 | Bots coded, human understands completely |
| 6 | Bots coded, human understands mostly |
| 7 | Human specced, bots coded |
| 8 | Bots planned, human approved |
| 9 | Human fired-and-forgot |
| 10 | Rogue bots, zero human attention |
Levels 0-8 are welcome here with proper disclosure. Levels 9-10 (autonomous bots acting without a human reviewing this specific change) are out of scope for this project unless explicitly authorized by a maintainer — see the article for the full description of each level.
Please fill out the pull request template - it's pre-filled when you open a PR on GitHub.
Labels are applied automatically based on your branch name and changed files (see .github/labeler.yml), which also drives the release notes categorization (.github/release.yml). Prefixing your branch name accordingly helps:
fix/…orhotfix/…: bug fixfeature/…orimprove/…: new feature or enhancementdocs/…: documentationpackaging/…: build/packagingtooling/…: toolingcli/…: CLI-specific change
As the aim of this project is to be carried out on large-scale IT infrastructures, security is one of the development challenges. It's enforced through automated checks, which are mainly executed in CI. But there are a few best practices to bear in mind:
- give preference to the standard Python library, even it's longer to develop
- or consider adding an additional third-party dependency (interest, consequences, linked dependencies, etc.)
- take security alerts into account
Feel free to use the IDE you love. Here come configurations for some popular IDEs to fit those guidelines.
It's the IDE used by the main developer, so the configuration is tracked on this repository until new contributors with other IDEs are joining the project.
Configuration is under: .vscode/settings.json