Initial commit

2025-11-30 08:55:38 +08:00
commit 4e7b2cfa56
19 changed files with 6651 additions and 0 deletions
--- a/references/contributing.md
+++ b/references/contributing.md
@@ -0,0 +1,626 @@
+# UI5 Linter - Contributing Guide
+
+**Source**: [https://github.com/UI5/linter/blob/main/CONTRIBUTING.md](https://github.com/UI5/linter/blob/main/CONTRIBUTING.md)
+**Last Updated**: 2025-11-21
+**UI5 Linter Version**: 1.20.5
+
+---
+
+## Overview
+
+This guide covers how to contribute to the UI5 Linter project, including reporting issues, requesting features, and submitting code changes. Following these guidelines ensures your contributions are processed efficiently.
+
+---
+
+## Before You Contribute
+
+### Check Existing Work
+
+**Search First**:
+```bash
+# Check if issue already exists
+[https://github.com/UI5/linter/issues](https://github.com/UI5/linter/issues)
+
+# Check the Task Board for related work
+[https://github.com/orgs/SAP/projects/110](https://github.com/orgs/SAP/projects/110)
+```
+
+**Why**: Avoid duplicate reports and identify ongoing work that might address your needs.
+
+---
+
+## Reporting Issues
+
+### When to Report Issues
+
+**✅ Report Issues For**:
+- Bugs in UI5 Linter functionality
+- Problems with linting rules
+- Autofix errors or unexpected behavior
+- Documentation errors or gaps
+- Feature requests for new rules or capabilities
+
+**❌ DO NOT Report Issues For**:
+- Problems with UI5 Linter dependencies (report to those projects)
+- Issues with non-public UI5 APIs
+- General UI5 questions (use community channels instead)
+- Security vulnerabilities (follow security policy instead)
+
+---
+
+### Issue Reporting Standards
+
+**Essential Requirements for Bug Reports**:
+
+1. **Good Summary**
+   - Be specific to the issue
+   - Include what failed, not just "linter doesn't work"
+
+   **Example**:
+   ```
+   ✅ Good: "no-globals rule fails to detect sap.ui.getCore() in arrow functions"
+   ❌ Bad: "Linter broken"
+   ```
+
+2. **Reproducible Bug**
+   - Provide step-by-step instructions
+   - Include minimal code example
+   - Specify exact commands run
+
+   **Example**:
+   ```markdown
+   ## Steps to Reproduce
+   1. Create file `test.js` with content:
+      ```javascript
+      const fn = () => sap.ui.getCore().byId("test");
+      ```
+   2. Run: `ui5lint test.js`
+   3. Expected: Warning about global usage
+   4. Actual: No warning shown
+   ```
+
+3. **Environment Details**
+   - UI5 Linter version: `ui5lint --version`
+   - Node.js version: `node --version`
+   - npm version: `npm --version`
+   - Operating system: Windows 11, macOS 14, Ubuntu 22.04, etc.
+   - UI5 version in your project
+
+4. **Expected vs Actual Behavior**
+   - What you expected to happen
+   - What actually happened
+   - Include error messages (full stack trace if applicable)
+
+5. **Maximum Context**
+   - Configuration file (ui5lint.config.js)
+   - Relevant code snippets
+   - Log output with `--verbose` flag
+
+   **Example**:
+   ```bash
+   ui5lint --verbose test.js 2>&1 | tee debug.log
+   ```
+
+---
+
+### Bug Report Template
+
+Use the GitHub issue template or follow this format:
+
+```markdown
+## Bug Description
+Brief description of the issue
+
+## Steps to Reproduce
+1. Step one
+2. Step two
+3. Step three
+
+## Expected Behavior
+What should happen
+
+## Actual Behavior
+What actually happens
+
+## Environment
+- UI5 Linter version: 1.20.5
+- Node.js version: 20.11.0
+- npm version: 10.2.0
+- OS: Ubuntu 22.04
+- UI5 version: 1.120.0
+
+## Configuration
+```javascript
+// ui5lint.config.mjs
+export default {
+  ignores: ["webapp/thirdparty/**"]
+};
+```
+
+## Additional Context
+- Verbose output attached
+- Related to issue #123
+```
+
+---
+
+### Issue Reporting Rules
+
+**Critical Rules**:
+- ✅ **One bug per report** - Open separate issues for different problems
+- ✅ **English only** - All issues must be in English
+- ✅ **Use template** - Follow the provided issue template
+- ✅ **Search first** - Check for duplicates before reporting
+- ❌ **No sensitive data** - Don't include credentials, tokens, or proprietary code
+
+---
+
+## Security Issues
+
+**🔒 DO NOT create public GitHub issues for security vulnerabilities**
+
+Instead:
+1. Review the [Security Policy](https://github.com/UI5/linter/security/policy)
+2. Report vulnerabilities through GitHub's private security advisory feature
+3. Follow responsible disclosure practices
+
+**Why**: Public disclosure puts users at risk before a fix is available.
+
+---
+
+## Feature Requests
+
+### When to Request Features
+
+**Good Feature Requests**:
+- New linting rules for UI5 2.x compatibility
+- Additional autofix capabilities
+- New output formats
+- Performance improvements
+- Developer experience enhancements
+
+**How to Request**:
+1. Check [Task Board](https://github.com/orgs/SAP/projects/110) for existing work
+2. Search [issues](https://github.com/UI5/linter/issues) for similar requests
+3. Open issue with `Feature` label
+4. Describe use case and expected behavior
+5. Explain why this would benefit other users
+
+**Feature Request Template**:
+```markdown
+## Feature Description
+Clear description of the proposed feature
+
+## Use Case
+Why is this feature needed? What problem does it solve?
+
+## Proposed Solution
+How should this feature work?
+
+## Alternatives Considered
+What other approaches did you consider?
+
+## Additional Context
+- Screenshots, mockups, examples
+- Related issues or RFCs
+```
+
+---
+
+## Issue Labels
+
+Understanding issue labels helps track and prioritize issues.
+
+### Type Labels
+
+| Label | Description |
+|-------|-------------|
+| **Bug** | Something isn't working correctly |
+| **Feature** | New feature or enhancement request |
+
+### UI5 Linter-Specific Labels
+
+| Label | Description |
+|-------|-------------|
+| **detection** | Related to rule detection logic |
+| **autofix** | Related to automatic fixing |
+| **documentation** | Documentation improvements |
+| **needs triage** | Issue needs review by maintainers |
+
+### Status Labels (Open Issues)
+
+| Label | Description |
+|-------|-------------|
+| **information required** | More details needed from reporter |
+| **good first issue** | Suitable for new contributors |
+| **help wanted** | Community contributions welcome |
+
+### Status Labels (Closed Issues)
+
+| Label | Description |
+|-------|-------------|
+| **duplicate** | Already reported elsewhere |
+| **invalid** | Not a valid issue |
+| **wontfix** | Won't be fixed/implemented |
+
+---
+
+## Code Contributions
+
+### Contribution Process
+
+**Step-by-Step Workflow**:
+
+1. **Confirm Change is Welcome**
+   ```bash
+   # Check Task Board for related work
+   [https://github.com/orgs/SAP/projects/110](https://github.com/orgs/SAP/projects/110)
+
+   # Comment on related issue or create discussion
+   ```
+
+2. **Fork the Repository**
+   ```bash
+   # Fork via GitHub UI, then clone
+   git clone [https://github.com/YOUR-USERNAME/linter.git](https://github.com/YOUR-USERNAME/linter.git)
+   cd linter
+   ```
+
+3. **Create Branch**
+   ```bash
+   # Use descriptive branch name
+   git checkout -b fix/no-globals-arrow-functions
+   # or
+   git checkout -b feat/new-rule-name
+   ```
+
+4. **Make Changes**
+   ```bash
+   # Follow development conventions
+   # See docs/Guidelines.md and docs/Development.md
+
+   # Run tests
+   npm test
+
+   # Run linter
+   npm run lint
+   ```
+
+5. **Commit Changes**
+   ```bash
+   # Follow Conventional Commits format
+   git commit -m "fix(no-globals): Detect globals in arrow functions
+
+   - Add support for arrow function expressions
+   - Update test fixtures
+   - Add regression test for issue #123"
+   ```
+
+6. **Push Branch**
+   ```bash
+   git push origin fix/no-globals-arrow-functions
+   ```
+
+7. **Create Pull Request**
+   - Use GitHub UI to create PR
+   - Fill out PR template
+   - Link related issues
+   - Provide clear description
+
+8. **Accept DCO**
+   - CLA Assistant will prompt for Developer Certificate of Origin
+   - Required for first-time contributors
+   - Accept to proceed with PR
+
+9. **Address Review Feedback**
+   ```bash
+   # Make requested changes
+   git add .
+   git commit -m "fix: Address review feedback"
+   git push
+   ```
+
+10. **Merge**
+    - Maintainers will merge approved PRs
+    - Squash merge is typically used
+    - Credit will be given in commit and release notes
+
+---
+
+### Development Conventions
+
+**See Full Guides**:
+- **Guidelines.md** - Coding standards, testing, git workflow
+- **Development.md** - Setup, SAPUI5 types, autofix development
+
+**Key Standards**:
+
+**Code Style**:
+```bash
+# ESLint enforced
+npm run lint
+
+# Fix auto-fixable issues
+npm run lint -- --fix
+```
+
+**Testing**:
+```bash
+# Run all tests (CI-style)
+npm test
+
+# Run unit tests once
+npm run unit
+
+# Run unit tests in watch mode
+npm run unit-watch
+```
+
+**Git Workflow**:
+```bash
+# Use rebase, NOT merge
+git fetch origin
+git rebase origin/main
+
+# NO merge commits
+# Maintainers will squash on merge
+```
+
+**Commit Message Format**:
+```
+type(scope): Description
+
+- Bullet point details
+- Another detail
+
+Fixes #123
+```
+
+**Types**: fix, feat, docs, style, refactor, test, chore
+
+**Scope**: Rule name, component, or area affected
+
+**Example**:
+```
+fix(xml-transpiler): Log unknown namespaces as verbose instead of warning
+
+- Changes log level for unknown XML namespaces
+- Reduces noise in common scenarios
+- Aligns with UI5 best practices
+
+Fixes #456
+```
+
+---
+
+### Developer Certificate of Origin (DCO)
+
+**What is DCO?**
+
+The Developer Certificate of Origin is a lightweight alternative to traditional CLAs (Contributor License Agreements). It certifies that you have the right to submit your contribution.
+
+**How to Accept**:
+1. First PR triggers CLA Assistant
+2. Click link and accept DCO terms
+3. Terms follow [developercertificate.org](https://developercertificate.org/)
+4. One-time acceptance covers all future PRs
+
+**DCO Statement**:
+> By submitting this pull request, I certify that my contribution is made under the terms of the Developer Certificate of Origin.
+
+---
+
+### AI-Generated Code
+
+**Guidelines for AI-Assisted Contributions**:
+
+If your contribution includes AI-generated code:
+1. Follow SAP's [AI Code Contribution Guidelines](https://github.com/SAP/.github/blob/main/CONTRIBUTING_USING_GENAI.md)
+2. Review and understand all AI-generated code
+3. Ensure code meets project standards
+4. Test thoroughly
+5. Disclose AI assistance in PR description (optional but recommended)
+
+**Important**:
+- You are responsible for all submitted code, regardless of origin
+- AI-generated code must pass all quality checks
+- Maintainers may request clarification or changes
+
+---
+
+## RFC Process (Request for Comments)
+
+**When to Write an RFC**:
+- Major new features
+- Breaking changes
+- Architectural decisions
+- Significant API changes
+
+**RFC Template**:
+[https://github.com/UI5/linter/blob/main/rfcs/0000-template.md](https://github.com/UI5/linter/blob/main/rfcs/0000-template.md)
+
+**Process**:
+1. Copy template to `rfcs/NNNN-my-feature.md`
+2. Fill out all sections
+3. Create PR with RFC
+4. Discuss in PR comments
+5. Iterate based on feedback
+6. Final decision by maintainers
+
+**Note**: Currently no active RFCs, but process is available for major proposals.
+
+---
+
+## Contribution Best Practices
+
+### Before Submitting PR
+
+**✅ Checklist**:
+- [ ] Tests pass: `npm test`
+- [ ] Linter passes: `npm run lint`
+- [ ] Code follows guidelines
+- [ ] Commit messages follow conventions
+- [ ] Branch rebased on latest main
+- [ ] No merge commits
+- [ ] Related issue referenced
+- [ ] PR template completed
+
+### During Review
+
+**✅ Good Practices**:
+- Respond to feedback promptly
+- Ask questions if review unclear
+- Make requested changes quickly
+- Be open to suggestions
+- Keep discussion professional
+
+**❌ Avoid**:
+- Force pushing after review (unless requested)
+- Adding unrelated changes
+- Arguing without technical justification
+- Ignoring review feedback
+
+### After Merge
+
+**✅ Follow Up**:
+- Monitor for issues related to your change
+- Be available to fix regressions
+- Update documentation if needed
+- Close related issues
+
+---
+
+## Common Contribution Scenarios
+
+### Scenario 1: Fix a Bug
+
+```bash
+# 1. Find and confirm bug
+ui5lint test.js --verbose
+
+# 2. Create issue if not exists
+# GitHub issue #789
+
+# 3. Fork and branch
+git clone [https://github.com/YOUR-USERNAME/linter.git](https://github.com/YOUR-USERNAME/linter.git)
+git checkout -b fix/issue-789
+
+# 4. Write failing test
+# test/lib/rules/no-globals.js
+
+# 5. Fix the bug
+# src/linter/rules/no-globals.js
+
+# 6. Verify test passes
+npm run unit
+
+# 7. Commit
+git commit -m "fix(no-globals): Detect globals in arrow functions
+
+- Add support for ArrowFunctionExpression
+- Add test case for issue #789
+- Update documentation
+
+Fixes #789"
+
+# 8. Push and create PR
+git push origin fix/issue-789
+```
+
+---
+
+### Scenario 2: Add New Rule
+
+```bash
+# 1. Create RFC or discussion first (for major rules)
+# 2. Get approval from maintainers
+
+# 3. Fork and branch
+git checkout -b feat/new-rule-name
+
+# 4. Implement rule
+# src/linter/rules/new-rule-name.js
+
+# 5. Add tests
+# test/lib/rules/new-rule-name.js
+
+# 6. Add documentation
+# Update docs/Rules.md
+
+# 7. Run full test suite
+npm test
+
+# 8. Commit
+git commit -m "feat(rules): Add new-rule-name for detecting X
+
+- Implements new rule to detect Y
+- Adds comprehensive test coverage
+- Documents rule in Rules.md
+
+Implements #456"
+
+# 9. Push and create PR
+git push origin feat/new-rule-name
+```
+
+---
+
+### Scenario 3: Improve Documentation
+
+```bash
+# 1. Identify documentation gap
+# 2. Fork and branch
+git checkout -b docs/improve-autofix-guide
+
+# 3. Update documentation
+# docs/Scope-of-Autofix.md
+
+# 4. Commit
+git commit -m "docs(autofix): Clarify limitations for Core APIs
+
+- Add examples of unsupported APIs
+- Link to GitHub issues #619, #620
+- Improve troubleshooting section"
+
+# 5. Push and create PR
+git push origin docs/improve-autofix-guide
+```
+
+---
+
+## Resources for Contributors
+
+**Official Documentation**:
+- [Development Guide](https://github.com/UI5/linter/blob/main/docs/Development.md)
+- [Guidelines](https://github.com/UI5/linter/blob/main/docs/Guidelines.md)
+- [Rules Documentation](https://github.com/UI5/linter/blob/main/docs/Rules.md)
+
+**GitHub Resources**:
+- [Task Board](https://github.com/orgs/SAP/projects/110)
+- [Issues](https://github.com/UI5/linter/issues)
+- [Pull Requests](https://github.com/UI5/linter/pulls)
+- [Security Policy](https://github.com/UI5/linter/security/policy)
+
+**Community**:
+- [OpenUI5 Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com) - #tooling channel
+- [StackOverflow](http://stackoverflow.com/questions/tagged/ui5-tooling) - ui5-tooling tag
+
+---
+
+## Summary
+
+**Quick Reference**:
+
+**Report Bug**: Search → Create issue → Follow template → Provide context
+
+**Request Feature**: Search → Create issue → Describe use case → Explain benefit
+
+**Contribute Code**: Confirm welcome → Fork → Branch → Commit → PR → Review → Merge
+
+**Get Help**: Use community channels (Slack, StackOverflow), not GitHub issues
+
+---
+
+**Document Version**: 1.0
+**Last Verified**: 2025-11-21
+**Next Review**: 2026-02-21