Contributing

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.

Development#

Once you cloned the repository:

# install project as editable
python -m pip install -e .

# including development dependencies
python -m pip install -e .[dev]

# including documentation dependencies
python -m pip install -e .[docs]

# including testing dependencies
python -m pip install -e .[test]

# all inclusive
python -m pip install -e .[dev,docs,test]

# install git hooks
pre-commit install

Then follow the contribution guidelines.

Run the tests#

# install development dependencies
python -m pip install -e .[test]

# run tests
pytest

Build the documentation#

# install dependencies for documentation
python -m pip install -e .[docs,properdocs]

# build the documentation
properdocs build

Release workflow#

1. Fill the CHANGELOG.md
2. Change the version number in __about__.py
3. Apply a git tag with the relevant version: git tag -a 0.3.0 {git commit hash} -m "New awesome feature"
4. Push tag to main branch: git push origin 0.3.0

Guidelines#

Commit messages#

We (try to) 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 enhancement
• fix: bug fix
• docs: documentation only
• test: adding or fixing tests
• refactor: code change that neither fixes a bug nor adds a feature
• chore: maintenance (dependency bumps, housekeeping, etc.)
• ci: CI/CD configuration
• build: build system or packaging

Git hooks#

We use git hooks through pre-commit to enforce and automatically check some "rules". Please install it before to push any commit.

See the relevant configuration file: .pre-commit-config.yaml.

Code Style#

Make sure your code roughly follows PEP-8 and keeps things consistent with the rest of the code:

• docstrings: google-style is used to technically describe what code does or not.
• formatting: ruff format is used to automatically format the code without debate.
• sorted imports: ruff's isort rules are used to sort imports
• static analysis: ruff check is used to catch some dizziness and keep the source code healthy.

Pulls requests#

Pull requests are really welcome since you take the time to push or modify tests related to the code you edit or create. Please fill out the pull request template 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/... or hotfix/...: bug fix
• feature/... or improve/...: new feature or enhancement
• docs/...: documentation
• packaging/...: build/packaging
• tooling/...: tooling

Versioning and changelog#

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.

IDE proposed settings#

Feel free to use the IDE you love. Here come configurations for some popular IDEs to fit those guidelines.

Visual Studio Code#

{
    // JSON
    "[json]": {
        "editor.bracketPairColorization.enabled": true,
        "editor.defaultFormatter": "vscode.json-language-features",
        "editor.formatOnSave": true,
        "editor.guides.bracketPairs": "active",
        "editor.quickSuggestions": {
            "strings": true
        },
        "editor.suggest.insertMode": "replace",
        "files.insertFinalNewline": true
    },
    "json.format.enable": true,
    "json.schemaDownload.enable": true,
    // Markdown
    "markdown.updateLinksOnFileMove.enabled": "prompt",
    "markdown.updateLinksOnFileMove.enableForDirectories": true,
    "markdown.validate.enabled": true,
    "markdown.validate.fileLinks.markdownFragmentLinks": "warning",
    "markdown.validate.fragmentLinks.enabled": "warning",
    "[markdown]": {
        "editor.bracketPairColorization.enabled": true,
        "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
        "editor.formatOnSave": true,
        "editor.guides.bracketPairs": "active",
        "files.trimTrailingWhitespace": false
    },
    // Python
    "python.analysis.autoFormatStrings": true,
    "python.analysis.autoImportCompletions": true,
    "python.analysis.typeCheckingMode": "standard",
    "python.terminal.activateEnvInCurrentTerminal": true,
    "python.terminal.activateEnvironment": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestEnabled": true,  
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit"
        },
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.guides.bracketPairs": "active",
        "editor.rulers": [
            88
        ],
        "editor.wordWrapColumn": 88,
    },
    // TOML
    "[toml]": {
        "editor.defaultFormatter": "tamasfe.even-better-toml",
        "editor.formatOnSave": true,
    },
    // YAML
    "[yaml]": {
        // "editor.autoIndent": "keep",
        "editor.formatOnSave": true,
        "editor.insertSpaces": true,
        "editor.tabSize": 2,
        "diffEditor.ignoreTrimWhitespace": false,
        "editor.quickSuggestions": {
            "other": true,
            "comments": false,
            "strings": true
        }
    },
    // extensions
    "autoDocstring.guessTypes": true,
    "autoDocstring.docstringFormat": "google-notypes",
    "autoDocstring.generateDocstringOnEnter": false,
    "yaml.customTags": [
        "!ENV scalar",
        "!ENV sequence",
        "!relative scalar",
        "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
        "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
        "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
    ],
    "sonarlint.connectedMode.project": {
        "connectionId": "geojulien",
        "projectKey": "Guts_mkdocs-rss-plugin"
    }
}

AI Policy#

Contributors can use whatever tools they would like to craft their contributions, but there must be a human in the loop.

Contributors must read and review all LLM-generated code before marking a pull request as ready for review. The contributor is always the author and is fully accountable for their contributions, which includes ensuring their contributions are aligned with guidelines.

Contributors should be sufficiently confident that their contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be able to answer questions about their work by themselves during review.

Disclosure#

Community members are expected to be transparent and disclose AI usage in contributions submitted for review that contain substantial amounts of LLM-generated content.

"Substantial" means different things depending on the type of contribution:

• Code: any generation beyond single-line autocomplete, such as whole functions, tests, or algorithms.
• Documentation: anything more than a few words.

Disclosure is not penalized during PR review.

Contributors should note details on tool usage (such as models and prompts used) in PR descriptions.

To disclose it, please follow 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 public link to the session (chat/agent conversation) that produced the change, when available.

The scale, summarized:

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.

Copyright and licensing#

Using AI tools to regenerate copyrighted material does not remove the copyright. As per the GitHub TOS, contributors are responsible for ensuring they have the right to contribute code under the terms of the repository license. This responsibility applies equally to code written by hand, code generated by an AI tool, and code adapted from elsewhere.