📖 Add comprehensive contributor guide #938
Conversation
Add CONTRIBUTING.md with detailed guidance for new contributors including: - Development environment setup and prerequisites - Building the project (local and containers) - Container-based development workflow for testing all providers - Adding new rules with provider-specific examples - Adding new language support with file extension examples - Common issues and solutions (OOM, sed errors, connection issues) - Pull request process with commit conventions - Resource requirements (12GB RAM for all providers) This guide documents best practices learned from real contributor experience, including the recommended container-based workflow for regenerating demo-output.yaml with all providers. Signed-off-by: tsanders <[email protected]>
Link to new CONTRIBUTING.md guide to help contributors find development setup, testing workflows, and PR guidelines. Signed-off-by: tsanders <[email protected]>
WalkthroughAdded a new Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
CONTRIBUTING.md (4)
342-342: Use a heading instead of emphasis for "Best Practice".The line using "Best Practice:" should be formatted as a proper heading (### Best Practice:) rather than bold text for consistency with markdown structure and linting standards (MD036).
-**Best Practice:** Use semantic providers (nodejs, java, go, python) for symbol references, and builtin provider for patterns they cannot detect. +### Best Practice + +Use semantic providers (nodejs, java, go, python) for symbol references, and builtin provider for patterns they cannot detect.
431-431: Specify language for error output code block.The code fence at line 431 should specify a language (MD040). Since this shows error output, use
```txtor```bash.**Error:** -``` +```txt sed: 1: "external-providers/gene ...": invalid command code e--- `455-455`: **Specify language for error output code block.** The code fence at line 455 should specify a language (MD040). This shows error output, so use ` ```txt `. ```diff **Problem:** -``` +```txt Error: volume with name test-data already exists Error: pod analyzer already exists--- `600-601`: **Format bare URLs as markdown links.** Lines 600-601 contain bare URLs that should be formatted as markdown links (MD034) for better readability and maintainability. ```diff - - **GitHub Issues:** https://github.com/konveyor/analyzer-lsp/issues - - **Konveyor Slack:** https://kubernetes.slack.com/archives/CR85S82A2 + - **GitHub Issues:** [https://github.com/konveyor/analyzer-lsp/issues](https://github.com/konveyor/analyzer-lsp/issues) + - **Konveyor Slack:** [https://kubernetes.slack.com/archives/CR85S82A2](https://kubernetes.slack.com/archives/CR85S82A2)Alternatively, if you prefer a cleaner look:
- - **GitHub Issues:** https://github.com/konveyor/analyzer-lsp/issues - - **Konveyor Slack:** https://kubernetes.slack.com/archives/CR85S82A2 + - [GitHub Issues](https://github.com/konveyor/analyzer-lsp/issues) + - [Konveyor Slack](https://kubernetes.slack.com/archives/CR85S82A2)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
CONTRIBUTING.md(1 hunks)README.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
CONTRIBUTING.md
342-342: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
431-431: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
455-455: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
600-600: Bare URL used
(MD034, no-bare-urls)
601-601: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: test
- GitHub Check: benchmark (ubuntu-latest, linux)
- GitHub Check: benchmark (macos-latest, mac)
- GitHub Check: benchmark (windows-latest, windows)
- GitHub Check: test (windows-latest)
🔇 Additional comments (2)
README.md (1)
69-77: Clear and concise contribution section addition.The new Contributing section provides a helpful entry point to the comprehensive guide with well-chosen bullet points that highlight key topics. Link formatting is correct and well-placed in the README.
CONTRIBUTING.md (1)
1-611: Comprehensive and well-structured contributor guide.This is an excellent addition to the project. The guide covers all essential areas for contributors: setup, building, testing, container workflows, rule development, language support, troubleshooting, and PR processes. The examples are practical and helpful, and the troubleshooting section addresses real pain points (Java OOM, macOS sed issues, container connectivity). The resource requirements are clearly documented, and the container-based development workflow is thorough.
Beyond the minor markdown linting issues noted above, the content quality is high and will significantly help new contributors get productive quickly.
tsanders-rh
changed the title
Fix emoji prefix list to use the project's required prefixes: - Use 📖 for docs (not 📝) - Use 🌱 for infra/tests - Use⚠️ for breaking changes - Add note that PR titles must use text codes, not emoji characters Signed-off-by: tsanders <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
CONTRIBUTING.md (4)
342-342: Convert emphasis to a proper heading.Line 342 uses bold text ("Best Practice:") where a heading would be more semantically correct and improve document structure.
-**Best Practice:** Use semantic providers (nodejs, java, go, python) for symbol references, and builtin provider for patterns they cannot detect. +### Best Practice + +Use semantic providers (nodejs, java, go, python) for symbol references, and builtin provider for patterns they cannot detect.
431-433: Specify language for error output code block.Fenced code blocks should declare their language for syntax highlighting. The error shown here is shell output.
-**Error:** -``` +**Error:** +```bash sed: 1: "external-providers/gene ...": invalid command code e -``` +```
455-457: Specify language for error output code block.This error block also lacks a language declaration.
-**Problem:** -``` +**Problem:** +```text Error: volume with name test-data already exists Error: pod analyzer already exists -``` +```
605-606: Convert bare URLs to markdown links.Lines 605–606 use bare URLs, which should be wrapped in markdown link syntax for better readability and maintainability.
## Getting Help -- **GitHub Issues:** https://github.com/konveyor/analyzer-lsp/issues -- **Konveyor Slack:** https://kubernetes.slack.com/archives/CR85S82A2 +- **GitHub Issues:** [GitHub Issues](https://github.com/konveyor/analyzer-lsp/issues) +- **Konveyor Slack:** [Konveyor Slack](https://kubernetes.slack.com/archives/CR85S82A2)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
CONTRIBUTING.md
342-342: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
431-431: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
455-455: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
605-605: Bare URL used
(MD034, no-bare-urls)
606-606: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: e2e / e2e-api-integration-tests
🔇 Additional comments (2)
CONTRIBUTING.md (2)
1-618: Documentation is comprehensive and well-structured.This contributor guide effectively covers the full contributor journey from setup through PR submission. Strengths include:
- Clear distinction between builtin, nodejs, and java providers with practical use-case guidance
- Explicit resource requirements (12GB RAM) and troubleshooting for common pain points
- Step-by-step container-based workflow documented for reproducible testing
- Commit and PR title conventions with concrete examples matching the PR emoji prefix system
- Practical debugging guidance with specific commands for checking provider logs and pod status
The guide successfully bridges the gap between local development and container-based testing, which aligns well with the PR objective of documenting "best practices from contributor experience."
603-618: All referenced documentation files exist—no action needed.Verification confirms that all documentation files referenced in the "Getting Help" section are present in the repository:
README.md,docs/rules.md,docs/providers.md,docs/labels.md, andLICENSE. The CONTRIBUTING.md changes are correct as-is.
3 participants
Summary
Add a comprehensive CONTRIBUTING.md guide to help new contributors get started with the analyzer-lsp project.
What's Included
Why This Helps
This guide documents best practices learned from real contributor experience, including:
Changes
CONTRIBUTING.mdwith detailed contributor guidanceREADME.mdto link to the contributing guideChecklist
Summary by CodeRabbit