Contributing to Mulesoft Accelerators

This guide explains how to create and contribute documentation for Mulesoft Accelerators using MDX files.

Project Structure

mule-accelerators/
├── .github/                    # GitHub specific files
│   ├── ISSUE_TEMPLATE/        # Issue templates
│   └── workflows/             # GitHub Actions workflows
├── docs/                      # Documentation source files
│   ├── ai/                    # AI accelerator documentation
│   ├── healthcare/           # Healthcare accelerator documentation
│   ├── finance/              # Finance accelerator documentation
│   └── regulated-industries/ # Regulated industries documentation
├── examples/                  # Example implementations
│   ├── ai/                    # AI accelerator examples
│   ├── healthcare/           # Healthcare accelerator examples
│   └── finance/              # Finance accelerator examples
├── scripts/                   # Utility scripts
├── tests/                     # Test files
├── .gitignore                # Git ignore rules
├── CONTRIBUTING.md           # Contributing guidelines
├── LICENSE                   # Project license
├── README.md                 # Project readme
└── package.json              # Project dependencies

GitHub Project Structure

Branch Strategy

Main Branches
- main - Production-ready code
- develop - Development branch for integration
Feature Branches
- Format: feature/description-of-feature
- Example: feature/hipaa-compliance-docs
- Branch from: develop
- Merge to: develop
Release Branches
- Format: release/vX.Y.Z
- Example: release/v1.0.0
- Branch from: develop
- Merge to: main and develop
Hotfix Branches
- Format: hotfix/description-of-fix
- Example: hotfix/fix-syntax-error
- Branch from: main
- Merge to: main and develop

Issue Management

Issue Types
- 🐛 Bug Report
- ✨ Feature Request
- 📚 Documentation
- 🔧 Enhancement
- 🚀 Performance
- 🔒 Security
Issue Labels
- bug - Bug reports
- enhancement - Feature requests
- documentation - Documentation updates
- help wanted - Looking for contributors
- good first issue - Good for new contributors
- priority:high - High priority issues
- priority:medium - Medium priority issues
- priority:low - Low priority issues

Pull Request Process

PR Guidelines
- Use clear, descriptive titles
- Reference related issues
- Include screenshots for UI changes
- Update documentation as needed
- Follow code style guidelines
PR Review Process
- Require at least one review
- Pass all CI checks
- No merge conflicts
- Documentation updated
- Tests added/updated

Project Boards

Kanban Board Structure
- Backlog
- To Do
- In Progress
- Review
- Done
Sprint Planning
- Weekly sprints
- Sprint planning on Mondays
- Sprint review on Fridays
- Daily standups

Documentation Guidelines

Documentation Structure
- Keep documentation close to code
- Use clear, concise language
- Include examples
- Update docs with code changes
- Version documentation
Documentation Types
- README files
- API documentation
- Setup guides
- Architecture diagrams
- Troubleshooting guides

Code Review Guidelines

Review Checklist
- Code follows style guide
- Tests are included
- Documentation is updated
- No security vulnerabilities
- Performance considerations
- Accessibility compliance
Review Comments
- Be constructive
- Explain reasoning
- Suggest improvements
- Reference documentation

Release Process

Versioning
- Follow semantic versioning
- Update CHANGELOG.md
- Tag releases
- Create release notes
Deployment
- Automated deployment
- Staging environment
- Production environment
- Rollback procedures

Security Guidelines

Security Measures
- Regular security audits
- Dependency updates
- Security scanning
- Access control
Reporting Security Issues
- Use security advisory
- Private disclosure
- Responsible disclosure
- Security team contact

Community Guidelines

Code of Conduct
- Be respectful
- Be inclusive
- Be professional
- Report violations
Communication
- Use project channels
- Follow communication guidelines
- Be responsive
- Be helpful

Getting Started

Fork the Repository

git clone https://github.com/yourusername/mule-accelerators.git
cd mule-accelerators

Set Up Development Environment
```
npm install
npm run dev
```

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes
- Follow coding standards
- Write tests
- Update documentation
Submit Pull Request
- Create PR from feature branch
- Add description
- Request reviews
- Address feedback

Resources

Creating New MDX Files

Choose the Location
- Place your MDX file in the appropriate directory under pages/
- Use kebab-case for filenames (e.g., hipaa-compliance.mdx)

Basic MDX Structure

# Title of Your Page
 
Brief description of the accelerator or topic.
 
## Overview
 
Detailed explanation of what this accelerator does and its benefits.
 
## Features
 
- Feature 1
- Feature 2
- Feature 3
 
## Implementation Guide
 
Step-by-step instructions for implementing the accelerator.
 
### Prerequisites
 
- Requirement 1
- Requirement 2
 
### Steps
 
1. First step
2. Second step
3. Third step
 
## Best Practices
 
Important guidelines and recommendations.
 
## Troubleshooting
 
Common issues and their solutions.

MDX Features
- Use standard Markdown syntax
- Support for code blocks with syntax highlighting
- Can include React components (if configured)
- Support for frontmatter metadata

Code Examples

```xml
<mule>
  <!-- Your Mule configuration here -->
</mule>

Images and Assets
- Place images in the public directory
- Reference them in MDX:
```
![Alt text](/path/to/image.png)
```

Navigation

Update _meta.json

Add your page to the appropriate section in _meta.json

{
  "healthcare": {
    "title": "Healthcare Accelerators",
    "type": "page",
    "items": {
      "hipaa-compliance": "HIPAA Compliance",
      "hl7-integration": "HL7 Integration"
    }
  }
}

Internal Links
- Use relative paths for internal links
- Example: [HIPAA Compliance](/healthcare/hipaa-compliance)

Best Practices

Content Organization
- Start with a clear introduction
- Use consistent heading levels (h1, h2, h3)
- Break content into logical sections
- Include practical examples
Code Examples
- Use appropriate syntax highlighting
- Include comments explaining complex parts
- Provide complete, working examples
- Consider different scenarios
Documentation Style
- Be concise and clear
- Use active voice
- Include prerequisites and requirements
- Provide troubleshooting guidance
Images and Diagrams
- Use high-quality images
- Include alt text for accessibility
- Keep file sizes optimized
- Use appropriate formats (PNG for diagrams, JPEG for photos)

Local Development

Setup

# Clone the repository
git clone https://github.com/yourusername/mule-accelerators.git
cd mule-accelerators
 
# Install dependencies
npm install
 
# Start development server
npm run dev

Preview Changes
- Visit http://localhost:3000
- Navigate to your new page
- Check formatting and links
- Verify code examples
Testing
- Ensure all links work
- Verify code examples are properly formatted
- Check mobile responsiveness
- Test dark/light mode

Contributing Process

Create a Branch

git checkout -b feature/your-feature-name

Make Changes
- Create or modify MDX files
- Update navigation if needed
- Add any new assets

Commit Changes

git add .
git commit -m "Add new accelerator documentation"

Push Changes

git push origin feature/your-feature-name

Create Pull Request
- Go to GitHub repository
- Create new pull request
- Add description of changes
- Request review from maintainers

Resources

Einstein