zhongwei/gh-secondsky-sap-skills-skills-sapui5-linter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-secondsky-sap-skills-ski…/references/contributing.md
Zhongwei Li 4e7b2cfa56 Initial commit
2025-11-30 08:55:38 +08:00

14 KiB
Raw Permalink Blame History

UI5 Linter - Contributing Guide

Source: 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:

# 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:

    ## Steps to Reproduce
1. Create file `test.js` with content:
   ```javascript
   const fn = () => sap.ui.getCore().byId("test");
    1. Run: ui5lint test.js
    2. Expected: Warning about global usage
    3. 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:

    ui5lint --verbose test.js 2>&1 | tee debug.log

Bug Report Template

Use the GitHub issue template or follow this format:

## 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

    # 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

    # 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

    # Use descriptive branch name
git checkout -b fix/no-globals-arrow-functions
# or
git checkout -b feat/new-rule-name

  4. Make Changes

    # Follow development conventions
# See docs/Guidelines.md and docs/Development.md

# Run tests
npm test

# Run linter
npm run lint

  5. Commit Changes

    # 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

    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

    # 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:

# ESLint enforced
npm run lint

# Fix auto-fixable issues
npm run lint -- --fix

Testing:

# 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:

# 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
  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
  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

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

# 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

# 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

# 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:

GitHub Resources:

Community:

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

Reference in New Issue View Git Blame Copy Permalink