From 8acb5d0ca5d0d422f9d5f60773bde120ba2ac01c Mon Sep 17 00:00:00 2001 From: Ajit Pratap Singh Date: Sat, 28 Feb 2026 02:54:47 +0530 Subject: [PATCH 1/3] community: add open-source health files, LLM discovery, and SEO improvements Sets up the full GitHub community health scaffold and discoverability layer: LLM & SEO Discovery: - llms.txt: structured LLM discovery file (llmstxt.org spec) with project overview, full API listing, doc links, capabilities, and repo layout Community Health Files: - CODE_OF_CONDUCT.md: Contributor Covenant 2.1 with enforcement guidelines - SUPPORT.md: support channels, response times, and supported versions table - GOVERNANCE.md: roles (users/contributors/committers/maintainers), decision-making process, release flow, and conflict resolution - CODEOWNERS: path-based automatic review assignment for all core packages GitHub Automation: - .github/FUNDING.yml: GitHub Sponsors button (ajitpratap0) - .github/labeler.yml: 14 path-based auto-label rules for PRs - .github/stale.yml: stale issue/PR config (60d stale, 14d close) - .github/workflows/labeler.yml: PR auto-labeler workflow (actions/labeler@v5) - .github/workflows/stale.yml: daily stale management (actions/stale@v9) Issue & Discussion Templates: - .github/ISSUE_TEMPLATE/config.yml: template chooser with 4 contact links - .github/ISSUE_TEMPLATE/documentation.md: docs improvement template - .github/DISCUSSION_TEMPLATE/q-and-a.md: structured Q&A template - .github/DISCUSSION_TEMPLATE/ideas.md: feature proposal template - .github/DISCUSSION_TEMPLATE/show-and-tell.md: community showcase template README Updates: - Community health badges (Contributor Covenant, Contributing, Governance, Support, Good First Issues count) - Enhanced Get Help table (added Docs Issues, Q&A, Ideas, Show & Tell channels) - Contributors section links to Good First Issues and Help Wanted filters Labels created on GitHub: stale, tokenizer, ast, wasm, showcase Co-Authored-By: Claude Sonnet 4.6 --- .github/DISCUSSION_TEMPLATE/ideas.md | 33 +++++++ .github/DISCUSSION_TEMPLATE/q-and-a.md | 27 ++++++ .github/DISCUSSION_TEMPLATE/show-and-tell.md | 26 ++++++ .github/FUNDING.yml | 4 + .github/ISSUE_TEMPLATE/config.yml | 15 ++++ .github/ISSUE_TEMPLATE/documentation.md | 34 ++++++++ .github/labeler.yml | 81 +++++++++++++++++ .github/stale.yml | 47 ++++++++++ .github/workflows/labeler.yml | 20 +++++ .github/workflows/stale.yml | 49 +++++++++++ CODEOWNERS | 30 +++++++ CODE_OF_CONDUCT.md | 68 +++++++++++++++ GOVERNANCE.md | 76 ++++++++++++++++ README.md | 29 +++++-- SUPPORT.md | 69 +++++++++++++++ llms.txt | 91 ++++++++++++++++++++ 16 files changed, 691 insertions(+), 8 deletions(-) create mode 100644 .github/DISCUSSION_TEMPLATE/ideas.md create mode 100644 .github/DISCUSSION_TEMPLATE/q-and-a.md create mode 100644 .github/DISCUSSION_TEMPLATE/show-and-tell.md create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.md create mode 100644 .github/labeler.yml create mode 100644 .github/stale.yml create mode 100644 .github/workflows/labeler.yml create mode 100644 .github/workflows/stale.yml create mode 100644 CODEOWNERS create mode 100644 CODE_OF_CONDUCT.md create mode 100644 GOVERNANCE.md create mode 100644 SUPPORT.md create mode 100644 llms.txt diff --git a/.github/DISCUSSION_TEMPLATE/ideas.md b/.github/DISCUSSION_TEMPLATE/ideas.md new file mode 100644 index 00000000..29e4c276 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/ideas.md @@ -0,0 +1,33 @@ +--- +labels: ["enhancement"] +--- + + + +## Summary + + + +## Motivation + + + +## Proposed API / CLI / Behaviour + + + +```go +// example usage +``` + +## Alternatives considered + + + +## Willingness to contribute + +- [ ] I can open an issue and submit a PR after community discussion +- [ ] I'd love help from maintainers / other contributors +- [ ] I'm just sharing an idea ā€” no commitment diff --git a/.github/DISCUSSION_TEMPLATE/q-and-a.md b/.github/DISCUSSION_TEMPLATE/q-and-a.md new file mode 100644 index 00000000..b4e7cb48 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/q-and-a.md @@ -0,0 +1,27 @@ +--- +labels: ["question"] +--- + + + +## What are you trying to do? + + + +## What have you tried? + + + +```go +// your code here +``` + +## What happened? + + + +## Environment + +- **GoSQLX version**: +- **Go version**: +- **OS**: diff --git a/.github/DISCUSSION_TEMPLATE/show-and-tell.md b/.github/DISCUSSION_TEMPLATE/show-and-tell.md new file mode 100644 index 00000000..3d76fb48 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/show-and-tell.md @@ -0,0 +1,26 @@ +--- +labels: ["showcase"] +--- + + + +## What did you build? + + + +## How are you using GoSQLX? + + + +## Links + + + +## Benchmark / impact (optional) + + + +--- + +*Want to be featured in the README's "Who's Using GoSQLX" section? +Mention it in your post or [open an issue](https://github.com/ajitpratap0/GoSQLX/issues/new?title=Add%20our%20project%20to%20users).* diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..4422765d --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,4 @@ +# Funding options for GoSQLX +# These links appear as a "Sponsor" button on the repository + +github: [ajitpratap0] diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..e16a49b8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,15 @@ +blank_issues_enabled: false + +contact_links: + - name: šŸ’¬ Ask a question (GitHub Discussions) + url: https://github.com/ajitpratap0/GoSQLX/discussions/new?category=q-a + about: Usage questions, "how do Iā€¦" and general help + - name: šŸ’” Propose a feature idea (Discussions) + url: https://github.com/ajitpratap0/GoSQLX/discussions/new?category=ideas + about: Discuss a new feature before filing an issue + - name: šŸ“– Documentation (pkg.go.dev) + url: https://pkg.go.dev/github.com/ajitpratap0/GoSQLX + about: API reference and generated docs + - name: šŸ”’ Security vulnerability + url: https://github.com/ajitpratap0/GoSQLX/security/advisories/new + about: Report a security issue privately ā€” do NOT use public issues diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 00000000..877ddafa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,34 @@ +--- +name: šŸ“– Documentation improvement +about: Report missing, incorrect, or confusing documentation +title: 'docs: ' +labels: documentation +assignees: '' +--- + +## What documentation needs improvement? + + + +**File / section**: + +## What is wrong or missing? + + + +## What should it say instead? + + + +## Why does this matter? + + + +## Would you like to contribute the fix? + +- [ ] Yes, I can submit a PR +- [ ] No, I'd like someone else to fix it + +--- + +**GoSQLX version**: diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 00000000..6522f39c --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,81 @@ +# Automated PR labeling via actions/labeler +# Triggered by .github/workflows/labeler.yml + +parser: + - changed-files: + - any-glob-to-any-file: + - 'pkg/sql/parser/**' + +tokenizer: + - changed-files: + - any-glob-to-any-file: + - 'pkg/sql/tokenizer/**' + +ast: + - changed-files: + - any-glob-to-any-file: + - 'pkg/sql/ast/**' + +security: + - changed-files: + - any-glob-to-any-file: + - 'pkg/sql/security/**' + - 'cmd/gosqlx/internal/validate/**' + +linter: + - changed-files: + - any-glob-to-any-file: + - 'pkg/linter/**' + +lsp: + - changed-files: + - any-glob-to-any-file: + - 'pkg/lsp/**' + +cli: + - changed-files: + - any-glob-to-any-file: + - 'cmd/gosqlx/**' + +documentation: + - changed-files: + - any-glob-to-any-file: + - 'docs/**' + - '*.md' + - 'llms.txt' + +performance: + - changed-files: + - any-glob-to-any-file: + - 'pkg/metrics/**' + - 'performance_baselines.json' + - '**/*_bench_test.go' + - '**/*benchmark*' + +dialects: + - changed-files: + - any-glob-to-any-file: + - 'pkg/sql/keywords/**' + +ci-cd: + - changed-files: + - any-glob-to-any-file: + - '.github/workflows/**' + - 'Taskfile.yml' + - '.goreleaser.yml' + +python: + - changed-files: + - any-glob-to-any-file: + - 'python/**' + - 'pkg/cbinding/**' + +wasm: + - changed-files: + - any-glob-to-any-file: + - 'wasm/**' + +transform: + - changed-files: + - any-glob-to-any-file: + - 'pkg/transform/**' diff --git a/.github/stale.yml b/.github/stale.yml new file mode 100644 index 00000000..79a9a1b3 --- /dev/null +++ b/.github/stale.yml @@ -0,0 +1,47 @@ +# Stale issue and PR management +# https://github.com/actions/stale + +# Issues +daysUntilStale: 60 +daysUntilClose: 14 +staleLabel: stale +exemptLabels: + - pinned + - security + - P0 + - P1 + - bug + - good first issue + - help wanted + +staleIssueMessage: > + This issue has been automatically marked as stale because it has not had + activity for 60 days. It will be closed in 14 days unless there is new + activity or it is labelled `pinned`, `bug`, or `help wanted`. + + If this issue is still relevant, please leave a comment explaining the + current status or add context so a maintainer can re-prioritize it. + + Thank you for contributing to GoSQLX! + +closeIssueMessage: > + This issue has been automatically closed due to 14 days of inactivity + after being marked stale. It can be re-opened if it becomes relevant again. + +# Pull requests +stalePrMessage: > + This pull request has been automatically marked as stale because it has + not had activity for 60 days. It will be closed in 14 days unless there + is new activity. + + If you are still working on this PR, please leave a comment or push a + new commit. If you need help getting it over the finish line, mention + @ajitpratap0 and we will assist. + +closePrMessage: > + This pull request has been automatically closed due to 14 days of + inactivity after being marked stale. Please reopen it if you want + to continue the work. + +# Don't mark issues created within the last 7 days as stale +minimumCreatedAt: 7 diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 00000000..5f1ba2d3 --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,20 @@ +name: Label PRs + +on: + pull_request_target: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + label: + name: Apply labels + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v5 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + configuration-path: .github/labeler.yml + sync-labels: false diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 00000000..c558db87 --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,49 @@ +name: Mark stale issues and PRs + +on: + schedule: + - cron: '30 1 * * *' # 01:30 UTC daily + workflow_dispatch: + +permissions: + issues: write + pull-requests: write + +jobs: + stale: + name: Stale + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v9 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + days-before-stale: 60 + days-before-close: 14 + stale-issue-label: stale + exempt-issue-labels: 'pinned,security,P0,P1,bug,good first issue,help wanted' + stale-issue-message: > + This issue has been automatically marked as stale because it has not had + activity for 60 days. It will be closed in 14 days unless there is new + activity or it is labelled `pinned`, `bug`, or `help wanted`. + + If this issue is still relevant, please leave a comment explaining the + current status or add context so a maintainer can re-prioritize it. + + Thank you for contributing to GoSQLX! + close-issue-message: > + This issue has been automatically closed due to 14 days of inactivity + after being marked stale. It can be re-opened if it becomes relevant again. + stale-pr-message: > + This pull request has been automatically marked as stale because it has + not had activity for 60 days. It will be closed in 14 days unless there + is new activity. + + If you are still working on this PR, please leave a comment or push a + new commit. If you need help getting it over the finish line, mention + @ajitpratap0 and we will assist. + close-pr-message: > + This pull request has been automatically closed due to 14 days of + inactivity after being marked stale. Please reopen it if you want + to continue the work. + days-before-issue-stale: 60 + days-before-pr-stale: 60 diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 00000000..3bd6f993 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,30 @@ +# CODEOWNERS ā€” automatic review requests for PRs +# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Global default ā€” maintainer reviews everything +* @ajitpratap0 + +# Core parsing pipeline +/pkg/sql/tokenizer/ @ajitpratap0 +/pkg/sql/parser/ @ajitpratap0 +/pkg/sql/ast/ @ajitpratap0 +/pkg/models/ @ajitpratap0 + +# Security-sensitive code ā€” extra scrutiny +/pkg/sql/security/ @ajitpratap0 +/cmd/gosqlx/internal/validate/ @ajitpratap0 + +# CLI commands +/cmd/gosqlx/ @ajitpratap0 + +# Public high-level API (semver-sensitive) +/pkg/gosqlx/ @ajitpratap0 + +# Release infrastructure +/.github/workflows/release.yml @ajitpratap0 +/CHANGELOG.md @ajitpratap0 + +# Community health files +/CODE_OF_CONDUCT.md @ajitpratap0 +/GOVERNANCE.md @ajitpratap0 +/CONTRIBUTING.md @ajitpratap0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..2cc92f9a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,68 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in the GoSQLX community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members +- Helping newcomers learn ā€” we were all beginners once + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces ā€” GitHub issues, pull requests, discussions, code review comments ā€” and also applies when an individual is officially representing the project in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a private security advisory at https://github.com/ajitpratap0/GoSQLX/security/advisories/new or by emailing the maintainer directly (see the GitHub profile for contact information). + +All complaints will be reviewed and investigated promptly and fairly. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident. + +## Enforcement Guidelines + +Maintainers will follow these Community Impact Guidelines in determining consequences: + +### 1. Correction +**Impact**: Use of inappropriate language or other behavior deemed unprofessional. +**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning +**Impact**: A violation through a single incident or series of actions. +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. + +### 3. Temporary Ban +**Impact**: A serious violation of community standards, including sustained inappropriate behavior. +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. + +### 4. Permanent Ban +**Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..056d602b --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,76 @@ +# Governance + +## Overview + +GoSQLX is an open source project. This document describes how the project is governed, how decisions are made, and how contributors can take on more responsibility over time. + +## Roles + +### Users +Anyone who uses GoSQLX. Users are the most important people in the project ā€” feedback through issues, questions in Discussions, and bug reports directly shapes development priorities. + +### Contributors +Anyone who has submitted a merged pull request, a bug report that led to a fix, or substantive documentation improvements. Contributors are credited in release notes and the CHANGELOG. + +### Committers +Contributors who have demonstrated sustained, high-quality contributions across multiple areas of the codebase. Committers can: +- Merge pull requests after review +- Triage and label issues +- Cut release branches + +**Current committers**: [@ajitpratap0](https://github.com/ajitpratap0) + +To become a committer: contribute consistently for at least 3 months, demonstrate understanding of the architecture, and express interest in a GitHub Discussion or issue. + +### Maintainers +Responsible for the overall technical direction, release management, and final decisions on breaking changes. Maintainers are committers who have committed to long-term stewardship. + +**Current maintainer**: [@ajitpratap0](https://github.com/ajitpratap0) + +## Decision Making + +### Everyday decisions (bug fixes, docs, minor features) +Open a PR. If CI passes and a committer reviews it positively, it can be merged. No formal vote needed. + +### Significant features (new AST nodes, new dialect support, new packages) +1. Open an issue tagged `feature` with a design proposal (what, why, API sketch) +2. Allow 5 business days for community feedback +3. A committer signals approval (thumbs-up, "LGTM" comment, or review approval) +4. Proceed with implementation PR + +### Breaking changes +1. Open an issue tagged `breaking-change` ā€” mandatory minimum 14-day comment period +2. Document the migration path in `docs/MIGRATION.md` before merge +3. Requires explicit maintainer approval +4. Semantic versioning: breaking changes increment the minor version (v1.x.0) + +### Governance changes +Changes to this document require a GitHub Discussion open for at least 7 days with no unresolved objections. + +## Release Process + +GoSQLX follows [Semantic Versioning](https://semver.org/): +- **Patch** (v1.9.x): bug fixes, security patches, documentation ā€” no API changes +- **Minor** (v1.x.0): new features, new dialect support, new AST nodes ā€” backward compatible +- **Major** (vX.0.0): breaking API changes ā€” rare, requires 14-day notice + +Release cadence: ad-hoc driven by feature readiness and bug severity, roughly monthly. + +Releases are tagged on `main` and built automatically by GoReleaser. See `CONTRIBUTING.md` for the tagging workflow. + +## Conflict Resolution + +Disagreements on technical direction are resolved by: +1. Discussion in the relevant issue/PR (preferred) +2. A GitHub Discussion for broader input +3. Maintainer decision as a tiebreaker + +The goal is always rough consensus ā€” not unanimity, but no strong unaddressed objections. + +## Code of Conduct + +All participants are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md). + +## Acknowledgements + +This governance model is inspired by the [Node.js](https://github.com/nodejs/node/blob/main/GOVERNANCE.md) and [Go project](https://github.com/golang/proposal) governance models, simplified for a single-maintainer open source library. diff --git a/README.md b/README.md index 2061a29d..dc120651 100644 --- a/README.md +++ b/README.md @@ -1043,10 +1043,19 @@ See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed system design and [CHAN
+### Community Health + +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=flat-square)](CODE_OF_CONDUCT.md) +[![Contributing Guide](https://img.shields.io/badge/Contributing-Guide-brightgreen?style=flat-square)](CONTRIBUTING.md) +[![Governance](https://img.shields.io/badge/Governance-Model-blue?style=flat-square)](GOVERNANCE.md) +[![Support](https://img.shields.io/badge/Support-Channels-orange?style=flat-square)](SUPPORT.md) +[![Good First Issues](https://img.shields.io/github/issues/ajitpratap0/GoSQLX/good%20first%20issue?style=flat-square&label=Good%20First%20Issues&color=7057ff)](https://github.com/ajitpratap0/GoSQLX/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) + ### Join Our Community GitHub Discussions GitHub Issues +Ask a Question ### Get Help @@ -1054,8 +1063,11 @@ See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed system design and [CHAN |---------|---------|---------------| | [šŸ› Bug Reports](https://github.com/ajitpratap0/GoSQLX/issues/new?template=bug_report.md) | Report issues | Community-driven | | [šŸ’” Feature Requests](https://github.com/ajitpratap0/GoSQLX/issues/new?template=feature_request.md) | Suggest improvements | Community-driven | -| [šŸ’¬ Discussions](https://github.com/ajitpratap0/GoSQLX/discussions) | Q&A, ideas, showcase | Community-driven | -| [šŸ”’ Security](docs/SECURITY.md) | Report vulnerabilities | Best effort | +| [šŸ“– Docs Issues](https://github.com/ajitpratap0/GoSQLX/issues/new?template=documentation.md) | Fix docs | Community-driven | +| [šŸ’¬ Q&A](https://github.com/ajitpratap0/GoSQLX/discussions/new?category=q-a) | Questions & help | Community-driven | +| [šŸ’” Ideas](https://github.com/ajitpratap0/GoSQLX/discussions/new?category=ideas) | Propose features | Community-driven | +| [šŸŽ¤ Show & Tell](https://github.com/ajitpratap0/GoSQLX/discussions/new?category=show-and-tell) | Share your project | Community-driven | +| [šŸ”’ Security](https://github.com/ajitpratap0/GoSQLX/security/advisories/new) | Report vulnerabilities privately | Best effort |
@@ -1074,15 +1086,16 @@ See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed system design and [CHAN We love your input! We want to make contributing as easy and transparent as possible. Contributing Guide -Start Contributing +Good First Issues +Help Wanted #### Quick Contribution Guide -1. šŸ“ Fork the repo -2. šŸ”Ø Make your changes -3. āœ… Ensure tests pass (`go test -race ./...`) -4. šŸ“ Update documentation -5. šŸš€ Submit a PR +1. šŸ“ Fork the repo and create a feature branch +2. šŸ”Ø Make your changes following the [patterns in CLAUDE.md](CLAUDE.md) +3. āœ… Ensure tests pass with race detection (`go test -race ./...`) +4. šŸ“ Update CHANGELOG.md and relevant docs +5. šŸš€ Submit a PR ā€” CI runs automatically diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..ee466cf3 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,69 @@ +# Support + +## How to Get Help + +### šŸ› Found a bug? + +Open a [bug report](https://github.com/ajitpratap0/GoSQLX/issues/new?template=bug_report.md). Include: +- GoSQLX version (`gosqlx --version` or `const Version` in `pkg/gosqlx/gosqlx.go`) +- Go version (`go version`) +- Minimal reproducing SQL and Go snippet +- Expected vs actual behavior + +### šŸ’” Feature request? + +Open a [feature request](https://github.com/ajitpratap0/GoSQLX/issues/new?template=feature_request.md). Describe the SQL pattern you need parsed and the use case. + +### ā“ Questions and discussions + +For usage questions, design discussions, and "how do Iā€¦" questions, use [GitHub Discussions](https://github.com/ajitpratap0/GoSQLX/discussions): + +| Category | Use for | +|----------|---------| +| **Q&A** | Usage questions, API help | +| **Ideas** | Feature proposals before filing an issue | +| **Show and Tell** | Projects built with GoSQLX | +| **General** | Anything else | + +### šŸš€ Performance issues? + +Open a [performance issue](https://github.com/ajitpratap0/GoSQLX/issues/new?template=performance_issue.md) with benchmark output (`go test -bench=. -benchmem ./...`). + +### šŸ”’ Security vulnerabilities? + +**Do not open a public issue.** See [SECURITY.md](SECURITY.md) for responsible disclosure instructions. + +## Self-Help Resources + +| Resource | What it covers | +|----------|---------------| +| [Getting Started](docs/GETTING_STARTED.md) | Install and first parse in 5 minutes | +| [Usage Guide](docs/USAGE_GUIDE.md) | All API patterns with examples | +| [CLI Guide](docs/CLI_GUIDE.md) | Every CLI command and flag | +| [API Reference](docs/API_REFERENCE.md) | Complete function/type reference | +| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common errors and solutions | +| [Error Codes](docs/ERROR_CODES.md) | E1xxx / E2xxx / E3xxx reference | +| [SQL Compatibility](docs/SQL_COMPATIBILITY.md) | What SQL is supported per dialect | +| [Migration Guide](docs/MIGRATION.md) | Upgrading between versions | +| [pkg.go.dev](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX) | Generated Go API docs | + +## Response Times + +This is an open source project maintained in spare time. Typical response times: + +| Channel | Expected response | +|---------|------------------| +| Bug reports (with reproduction) | 1ā€“3 business days | +| Feature requests | 1ā€“2 weeks (discussion first) | +| Security vulnerabilities | 48 hours | +| GitHub Discussions | best-effort | + +## Supported Versions + +| Version | Status | Go requirement | +|---------|--------|----------------| +| v1.9.x | āœ… Active (current) | Go 1.21+ | +| v1.8.x | āš ļø Security fixes only | Go 1.21+ | +| < v1.8 | āŒ End of life | ā€” | + +Upgrade with: `go get github.com/ajitpratap0/GoSQLX@latest` diff --git a/llms.txt b/llms.txt new file mode 100644 index 00000000..94bb75ce --- /dev/null +++ b/llms.txt @@ -0,0 +1,91 @@ +# GoSQLX + +> High-performance SQL parsing SDK for Go ā€” 1.5M+ ops/sec, multi-dialect, zero-copy, race-free production library. + +GoSQLX is a production-ready SQL parsing library for Go that provides zero-copy tokenization, +recursive-descent parsing, and AST generation with comprehensive object pooling. It supports +PostgreSQL, MySQL, SQL Server, Oracle, SQLite, and Snowflake dialects, and ships a full-featured +CLI tool (`gosqlx`) for validation, formatting, linting, and security analysis. Apache-2.0 licensed. + +Current stable version: v1.9.0 (2026-02-28) + +## Core API + +- [Package gosqlx](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/gosqlx): High-level entry point ā€” `Parse()`, `Validate()`, `Format()`, `ParseWithDialect()`, `ParseWithRecovery()` +- [Package parser](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/sql/parser): Recursive-descent parser with one-token lookahead and object pooling +- [Package tokenizer](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer): Zero-copy SQL lexer with full UTF-8 support +- [Package ast](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/sql/ast): AST node types and visitor pattern +- [Package security](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/sql/security): SQL injection scanner ā€” tautology, UNION, time-based, comment-bypass patterns +- [Package linter](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/linter): 10 built-in lint rules (L001ā€“L010) +- [Package transform](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/transform): Programmatic SQL rewriting ā€” add WHERE, columns, JOINs, pagination +- [Package lsp](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX/pkg/lsp): Language Server Protocol server for IDE integration + +## Documentation + +- [Getting Started](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/GETTING_STARTED.md): Install and first parse in 5 minutes +- [Usage Guide](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/USAGE_GUIDE.md): Comprehensive patterns for all API surfaces +- [CLI Guide](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/CLI_GUIDE.md): `gosqlx validate`, `format`, `parse`, `analyze`, `lint`, `lsp` commands +- [API Reference](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/API_REFERENCE.md): Complete API documentation with examples +- [SQL Compatibility](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/SQL_COMPATIBILITY.md): Feature support matrix across 6 SQL dialects +- [Error Codes](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/ERROR_CODES.md): E1xxx tokenizer, E2xxx parser, E3xxx semantic, E4xxx unsupported +- [Security](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/SECURITY.md): SQL injection detection API, tautology patterns, UNION split +- [Architecture](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/ARCHITECTURE.md): Tokenizer ā†’ Parser ā†’ AST pipeline, object pooling design +- [Migration Guide](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/MIGRATION.md): Breaking change notes per version +- [Performance Tuning](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/PERFORMANCE_TUNING.md): Pool configuration, batch parsing, profiling tips +- [Linting Rules](https://github.com/ajitpratap0/GoSQLX/blob/main/docs/LINTING_RULES.md): L001ā€“L010 rule reference + +## Key Capabilities + +- **SQL dialects**: PostgreSQL (default), MySQL, SQL Server (T-SQL), Oracle, SQLite, Snowflake +- **DML**: SELECT (window functions, CTEs, set ops, LATERAL, DISTINCT ON), INSERT, UPDATE, DELETE, MERGE +- **DDL**: CREATE/ALTER/DROP TABLE, INDEX, VIEW, MATERIALIZED VIEW; SQLite PRAGMA and WITHOUT ROWID +- **Security scanner**: Tautology (1=1), UNION injection, time-based blind, comment bypass, stacked queries, dangerous functions ā€” 4 severity levels (CRITICAL/HIGH/MEDIUM/LOW) +- **Object pooling**: sync.Pool throughout; 60-80% memory reduction vs naive allocation +- **Thread safety**: race-free, validated with 20,000+ concurrent operations +- **CLI**: `gosqlx validate/format/parse/analyze/lint/lsp` with SARIF output for GitHub Code Scanning +- **LSP server**: real-time diagnostics, completion, hover, formatting for VS Code and any LSP client +- **Query transforms**: add WHERE filters, column projections, JOINs, pagination via composable rules +- **WASM**: browser-based SQL parsing/formatting/linting playground +- **Python bindings**: PyGoSQLX via ctypes FFI + +## Quick Start + +```go +import "github.com/ajitpratap0/GoSQLX/pkg/gosqlx" + +// Parse ā€” returns *ast.AST +tree, err := gosqlx.Parse("SELECT u.name, COUNT(o.id) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name") + +// Validate +err = gosqlx.Validate("SELECT * FROM users WHERE active = true") + +// Format +formatted, err := gosqlx.Format(sql, gosqlx.DefaultFormatOptions()) + +// Dialect-aware +tree, err = gosqlx.ParseWithDialect("SHOW TABLES", keywords.DialectMySQL) + +// Batch (reuses pool objects) +trees, err := gosqlx.ParseMultiple([]string{sql1, sql2, sql3}) +``` + +## Repository Layout + +- `pkg/gosqlx/` ā€” high-level API (start here) +- `pkg/sql/tokenizer/` ā€” zero-copy lexer +- `pkg/sql/parser/` ā€” recursive-descent parser +- `pkg/sql/ast/` ā€” AST node definitions + visitor +- `pkg/sql/security/` ā€” injection scanner +- `pkg/linter/` ā€” lint rules engine +- `pkg/transform/` ā€” query rewriting +- `pkg/lsp/` ā€” LSP server +- `cmd/gosqlx/` ā€” CLI implementation +- `examples/` ā€” runnable code examples +- `docs/` ā€” comprehensive documentation (25+ guides) + +## Optional + +- [CHANGELOG](https://github.com/ajitpratap0/GoSQLX/blob/main/CHANGELOG.md): Full version history +- [Contributing](https://github.com/ajitpratap0/GoSQLX/blob/main/CONTRIBUTING.md): How to contribute +- [GitHub Action](https://github.com/marketplace/actions/gosqlx-sql-validator): GoSQLX SQL Validator CI action +- [Python Bindings](https://github.com/ajitpratap0/GoSQLX/blob/main/python/README.md): PyGoSQLX From d62a7875fac3fc0cc5378bb82ed40db52f27beb3 Mon Sep 17 00:00:00 2001 From: Ajit Pratap Singh Date: Sat, 28 Feb 2026 10:06:49 +0530 Subject: [PATCH 2/3] chore: remove redundant stale.yml config and add markdownlintignore - Remove .github/stale.yml: actions/stale@v9 workflow already has all configuration inline as workflow inputs; the config file was a leftover from the deprecated stale GitHub App and caused confusion (two sources of truth for the same policy) - Add .markdownlintignore: exclude CODEOWNERS from markdownlint checks. CODEOWNERS uses # for comments but is not a Markdown file; the linter was incorrectly flagging the comment lines as bare H1 headings. Co-Authored-By: Claude Sonnet 4.6 --- .github/stale.yml | 47 --------------------------------------------- .markdownlintignore | 3 +++ 2 files changed, 3 insertions(+), 47 deletions(-) delete mode 100644 .github/stale.yml create mode 100644 .markdownlintignore diff --git a/.github/stale.yml b/.github/stale.yml deleted file mode 100644 index 79a9a1b3..00000000 --- a/.github/stale.yml +++ /dev/null @@ -1,47 +0,0 @@ -# Stale issue and PR management -# https://github.com/actions/stale - -# Issues -daysUntilStale: 60 -daysUntilClose: 14 -staleLabel: stale -exemptLabels: - - pinned - - security - - P0 - - P1 - - bug - - good first issue - - help wanted - -staleIssueMessage: > - This issue has been automatically marked as stale because it has not had - activity for 60 days. It will be closed in 14 days unless there is new - activity or it is labelled `pinned`, `bug`, or `help wanted`. - - If this issue is still relevant, please leave a comment explaining the - current status or add context so a maintainer can re-prioritize it. - - Thank you for contributing to GoSQLX! - -closeIssueMessage: > - This issue has been automatically closed due to 14 days of inactivity - after being marked stale. It can be re-opened if it becomes relevant again. - -# Pull requests -stalePrMessage: > - This pull request has been automatically marked as stale because it has - not had activity for 60 days. It will be closed in 14 days unless there - is new activity. - - If you are still working on this PR, please leave a comment or push a - new commit. If you need help getting it over the finish line, mention - @ajitpratap0 and we will assist. - -closePrMessage: > - This pull request has been automatically closed due to 14 days of - inactivity after being marked stale. Please reopen it if you want - to continue the work. - -# Don't mark issues created within the last 7 days as stale -minimumCreatedAt: 7 diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 00000000..9ee7dcf8 --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,3 @@ +# CODEOWNERS uses # for comments, which markdownlint mistakes for H1 headings. +# It is not a Markdown file. +CODEOWNERS From 55ab2c660091fb85375c60a3476aaa6a86e7dea7 Mon Sep 17 00:00:00 2001 From: Ajit Pratap Singh Date: Sat, 28 Feb 2026 10:17:33 +0530 Subject: [PATCH 3/3] fix: correct labeler.yml indentation and stale.yml redundancy labeler.yml: - Fix YAML indentation: nest any-glob-to-any-file as a proper child of changed-files (was at sibling indentation level, making changed-files: null and any-glob-to-any-file a separate unrelated matcher in the sequence) stale.yml: - Remove redundant days-before-issue-stale and days-before-pr-stale (both were set to 60, same as the global days-before-stale; per-type settings only needed when they differ from the global) - Add exempt-pr-labels: security/P0/P1/pinned/do-not-merge PRs should not be auto-closed by the stale bot Co-Authored-By: Claude Sonnet 4.6 --- .github/labeler.yml | 74 ++++++++++++++++++------------------- .github/workflows/stale.yml | 3 +- 2 files changed, 38 insertions(+), 39 deletions(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index 6522f39c..1c7d9e8e 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -3,79 +3,79 @@ parser: - changed-files: - - any-glob-to-any-file: - - 'pkg/sql/parser/**' + - any-glob-to-any-file: + - 'pkg/sql/parser/**' tokenizer: - changed-files: - - any-glob-to-any-file: - - 'pkg/sql/tokenizer/**' + - any-glob-to-any-file: + - 'pkg/sql/tokenizer/**' ast: - changed-files: - - any-glob-to-any-file: - - 'pkg/sql/ast/**' + - any-glob-to-any-file: + - 'pkg/sql/ast/**' security: - changed-files: - - any-glob-to-any-file: - - 'pkg/sql/security/**' - - 'cmd/gosqlx/internal/validate/**' + - any-glob-to-any-file: + - 'pkg/sql/security/**' + - 'cmd/gosqlx/internal/validate/**' linter: - changed-files: - - any-glob-to-any-file: - - 'pkg/linter/**' + - any-glob-to-any-file: + - 'pkg/linter/**' lsp: - changed-files: - - any-glob-to-any-file: - - 'pkg/lsp/**' + - any-glob-to-any-file: + - 'pkg/lsp/**' cli: - changed-files: - - any-glob-to-any-file: - - 'cmd/gosqlx/**' + - any-glob-to-any-file: + - 'cmd/gosqlx/**' documentation: - changed-files: - - any-glob-to-any-file: - - 'docs/**' - - '*.md' - - 'llms.txt' + - any-glob-to-any-file: + - 'docs/**' + - '*.md' + - 'llms.txt' performance: - changed-files: - - any-glob-to-any-file: - - 'pkg/metrics/**' - - 'performance_baselines.json' - - '**/*_bench_test.go' - - '**/*benchmark*' + - any-glob-to-any-file: + - 'pkg/metrics/**' + - 'performance_baselines.json' + - '**/*_bench_test.go' + - '**/*benchmark*' dialects: - changed-files: - - any-glob-to-any-file: - - 'pkg/sql/keywords/**' + - any-glob-to-any-file: + - 'pkg/sql/keywords/**' ci-cd: - changed-files: - - any-glob-to-any-file: - - '.github/workflows/**' - - 'Taskfile.yml' - - '.goreleaser.yml' + - any-glob-to-any-file: + - '.github/workflows/**' + - 'Taskfile.yml' + - '.goreleaser.yml' python: - changed-files: - - any-glob-to-any-file: - - 'python/**' - - 'pkg/cbinding/**' + - any-glob-to-any-file: + - 'python/**' + - 'pkg/cbinding/**' wasm: - changed-files: - - any-glob-to-any-file: - - 'wasm/**' + - any-glob-to-any-file: + - 'wasm/**' transform: - changed-files: - - any-glob-to-any-file: - - 'pkg/transform/**' + - any-glob-to-any-file: + - 'pkg/transform/**' diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index c558db87..319d1d35 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -21,6 +21,7 @@ jobs: days-before-close: 14 stale-issue-label: stale exempt-issue-labels: 'pinned,security,P0,P1,bug,good first issue,help wanted' + exempt-pr-labels: 'pinned,security,P0,P1,do not merge' stale-issue-message: > This issue has been automatically marked as stale because it has not had activity for 60 days. It will be closed in 14 days unless there is new @@ -45,5 +46,3 @@ jobs: This pull request has been automatically closed due to 14 days of inactivity after being marked stale. Please reopen it if you want to continue the work. - days-before-issue-stale: 60 - days-before-pr-stale: 60