@W-21315032 docs: add team documentation and development patterns #894
Draft
@W-21315032 docs: add team documentation and development patterns #894
Conversation
- Add docs/team/ structure for patterns, configs, runbooks - Add Web Component communication pattern documentation - Add debugging runbook for common issues - Add .claude/ folder to .gitignore for local AI-generated files This establishes team knowledge base with: - Web Components best practices (properties, events, Shadow DOM) - Common debugging scenarios and solutions - Development workflow guidelines - Testing patterns Benefits: - Onboard new contributors faster - Document tribal knowledge - Consistent patterns across components - Context preservation for AI assistants Work Item: @W-21315032
- Introduced CLAUDE.md to provide comprehensive documentation for the api-console v6 project. - Included sections on project overview, essential commands for development, testing, building, and code quality. - Detailed architecture, usage modes, component hierarchy, and AMF model architecture. - Outlined event-driven communication, page state management, and testing strategy. This documentation aims to enhance onboarding for new contributors and ensure consistent development practices.
…API Console v6 - Introduced comprehensive onboarding documentation for API Console v6, detailing its purpose, architecture, and usage modes. - Added architectural decision records (ADRs) to document key design choices and component patterns. - Included a release runbook outlining the step-by-step process for versioning and publishing updates. - Created a troubleshooting guide to assist developers with common issues encountered during development and release. This documentation enhances the knowledge base for the team, streamlines the onboarding process for new contributors, and ensures consistent practices across the project.
|
Thanks for the contribution! Unfortunately we can't verify the commit author(s): Alex Perez <a***@s***.com>. One possible solution is to add that email to your GitHub account. Alternatively you can change your commits to another email and force push the change. After getting your commits associated with your GitHub account, refresh the status of this Pull Request. |
… API Console - Added comprehensive sections on the development cycle, branch naming conventions, and release processes for both v6 and v7 of the API Console. - Included guidelines for managing component fixes, scheduling releases, and related team contacts to streamline collaboration. - Enhanced troubleshooting information for common issues related to NPM registry authentication and component version mismatches. This update aims to improve clarity and efficiency in the release management workflow, ensuring all team members are aligned on processes and responsibilities.
- Documents fix/ vs build/ vs wrapper (no prefix) branch patterns - Explains why build/ prevents version conflicts - Includes examples from W-21368901 workflow - Provides validation checklist and common mistakes Related: W-21315032
- Created docs/team/configs/ for team-wide tool configurations - Added README explaining purpose and usage - Examples: .editorconfig, .eslintrc, prettier configs - Differentiates between team configs (committed) and personal configs (local) Related: W-21315032
alexpmule
force-pushed
the
feat/W-21315032
branch
from
920206d to
686eb2b
Compare
…ming conventions - Added comprehensive section on commit message format (enforced by commitlint) - Documented all valid commit types (feat, fix, docs, etc.) - Provided good vs bad examples - Clarified that commitlint validates messages, NOT branch names - Updated comparison table to include commit message format - Added validation tips and troubleshooting Related: W-21315032
- Added commit message format requirements (enforced by commitlint) - Listed all valid commit types with examples - Provided good vs bad commit message examples - Added subject line rules and validation tips - Cross-reference to full documentation in docs/team/patterns/ Related: W-21315032
Removed: - v7 Release Process section (workflows belong in v7 repo) - LWC Migration Context section (v7-specific context) - Branch naming pattern reference to v7 Kept contextual references (ADR-003, version comparison table) that explain the architectural landscape from v6 perspective. Related: W-21315032
Added based on Feb 2026 Cursor New Features Session recommendations: - .cursorrules: Simple one-liner rules (GPG signing, commit format, testing) - .cursorignore: Exclude large files from AI context (improves performance) - .claude/: Folder structure for AI working files (gitignored) - README.md: Documentation for folder structure - context/cursor-claude-best-practices.md: Best practices from meetings Key improvements: - Better AI context management (excludes models, screenshots, lock files) - Clear separation: rules (simple) vs skills (complex workflows) - PM-thinking approach from Amit meeting integrated - Follows Cursor's rules → skills migration path Related: W-21315032
Added complete release workflow skill for api-console v6 and wrapper: Features: - Automated component update workflow - Version bumping and branch creation - GPG signing verification (mulesoft-git vs salesforce-git) - PR creation guidance (web UI vs gh CLI) - Wrapper update steps (anypoint-api-console) - Validation checklists and common issues Skill triggers: - 'update api console components' - 'release api console v6' - 'update wrapper' Updated .gitignore to commit skills (team workflows) while keeping other .claude/ content ignored (analyses, plans, temp). Related: W-21315032
Added comprehensive GPG configuration documentation: - docs/team/configs/git-gpg-setup.md: Complete setup guide for team - Option 1: Manual per-repo configuration - Option 2: Shell aliases (mulesoft-git/salesforce-git) - Option 3: Directory-based auto-configuration - GPG key setup for first-time users - Common issues and troubleshooting Updated references from personal aliases to generic instructions: - .cursorrules: Reference git-gpg-setup.md instead of hardcoded commands - .claude/skills/update-api-console-components/SKILL.md: - Updated step-by-step instructions with both alias and manual options - Made examples generic (yourname@ instead of alexperez@) - Added references to setup documentation - CLAUDE.md: Point to git-gpg-setup.md for configuration Why: mulesoft-git and salesforce-git are personal aliases, not available to other team members. New documentation provides setup options for all team members to configure their own Git/GPG credentials. Related: W-21315032
Updated references per Salesforce Inclusive Product Language initiative: - Use 'main branch' in narrative/documentation - Clarify technical reality: '(master in api-console repo)' - Commands remain functional with current branch names Files updated: - .claude/skills/update-api-console-components/SKILL.md - CLAUDE.md (release process, branch references) - docs/team/runbooks/api-console-v6-release.md Approach: Use inclusive language while acknowledging current repo state. Some component repos have both 'main' and 'master' branches but only one is active. This approach works for all cases. Related: W-21315032
|
This PR contains some terms that are considered warnings according to the Inclusive Product Language initiative
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Establishes comprehensive team documentation and development tooling configuration for api-console v6, following Cursor/Claude Code best practices from Feb 2026 internal sessions.
What's Included
📚 Team Documentation (
docs/team/)Patterns
fix/,build/, and wrapper branch patterns + Conventional Commits enforcement via commitlintConfigs
Runbooks
Onboarding
🤖 AI Assistant Configuration
Cursor Rules & Ignore
Skills (Automation Workflows)
/update api console components,/release api console v6📖 Root Documentation
CLAUDE.md Updates
🗂️ Repository Structure
.gitignore Updates
.claude/skills/(team workflows, committed).claude/content remains ignored (analyses, plans, temp)Key Improvements
1. GPG Configuration (Team-Friendly)
Before: References to personal aliases (
mulesoft-git,salesforce-git) that only work on Alex's machineAfter:
2. Cursor/Claude Code Integration
Before: No Cursor-specific configuration
After:
3. Branch Naming & Commitlint Documentation
Before: Conventions only in tribal knowledge
After:
fix/W-XXXXXvsbuild/X.X.XvsX.X.X(wrapper)4. v7 Content Cleanup
Before: v6 documentation included v7-specific workflows
After:
Benefits
For New Team Members
For Existing Team
For AI Assistants (Claude/Cursor)
Testing
echo "fix: test" | npx commitlintValidation Checklist
mulesoft-git/salesforce-gitreferences updated to generic instructionsRelated