Contributing Guide

​

Welcome Contributors!

​

About This Repository

​

Repository Structure

├── gradle/
│   ├── libs.versions.toml      # Dependency version management
├── lumo-ui/
│   ├── components-lab/         # UI components library
│   ├── plugin/                 # Gradle plugin implementation
│   └── scripts/                # Build & release scripts
│       ├── generate_templates.sh  # Regenerates UI templates
├── sample-android/             # Android sample app
│   ├── catalogue/              # Sample components showcase
│   ├── ui-components/          # Sample UI component implementations
├── sample-multiplatform/       # Multiplatform sample app
│   ├── android/                # Android runner module
│   ├── common/                 # Multiplatform catalogue module (contains all platform source sets)
│   ├── desktop/                # Desktop runner module
│   ├── ios/                    # iOS runner module
│   ├── web/                    # Web runner module

​

Key Components

​

lumo-ui/components-lab/

​

lumo-ui/plugin/

• LumoGradlePlugin.kt - Main plugin entry point
• LumoTask.kt - Task implementation with CLI options
• ComponentGenerator.kt - Component generation logic
• Template.kt - Template data structures
• SupportedComponents.kt - Enum of available components

​

Templates

​

Development Workflow

​

Prerequisites

• JDK 11 or higher
• Git
• Android Studio or IntelliJ IDEA (recommended)
• Basic knowledge of Kotlin and Jetpack Compose

​

Fork the Repository

1. Click the ‘Fork’ button at the top right of the repository page
2. This creates a copy of the repository in your GitHub account

​

Clone Your Fork

git clone https://github.com/your-username/lumo-ui.git
cd lumo-ui

​

Create a New Branch

git checkout -b feature/your-feature-name

• feature/component-name - For new components
• fix/issue-description - For bug fixes
• docs/description - For documentation changes
• refactor/description - For code refactoring

​

Make Your Changes

​

Code Style

# Check code style
./gradlew spotlessCheck

# Apply code style
./gradlew spotlessApply

​

Test Your Changes

​

Test the Plugin Locally

1. Publish the plugin to Maven Local:

./gradlew :lumo-ui:plugin:publishToMavenLocal

2. In a test project, use the local version:

// settings.gradle.kts
pluginManagement {
    repositories {
        mavenLocal()  // Add this
        mavenCentral()
        google()
    }
}

// build.gradle.kts
plugins {
    id("com.nomanr.plugin.lumo") version "1.2.5-SNAPSHOT"
}

3. Test the plugin commands:

./gradlew lumo --init
./gradlew lumo --setup
./gradlew lumo --add YourComponent

​

Test Sample Apps

./gradlew :sample-android:catalogue:installDebug

# Android
./gradlew :sample-multiplatform:android:installDebug

# Desktop
./gradlew :sample-multiplatform:desktop:run

# iOS (macOS only)
open sample-multiplatform/ios/iosApp.xcodeproj

​

Commit Your Changes

git add .
git commit -m "feat: add new AlertDialog component"

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

​

Push to Your Fork

git push origin feature/your-feature-name

​

Create a Pull Request

1. Go to the original repository on GitHub
2. Click “New Pull Request”
3. Select your fork and branch
4. Fill in the PR description:
   • What changes did you make?
   • Why did you make them?
   • Any related issues?
   • Screenshots (for UI changes)
5. Ensure checks pass
6. Allow maintainer edits
7. Submit the pull request

​

Contributing Different Types of Changes

​

Adding a New Component

1. Create the Component in lumo-ui/components-lab/src/commonMain/kotlin/com/nomanr/lumo/ui/components/:

package {{packageName}}

import androidx.compose.runtime.Composable

@Composable
fun MyNewComponent() {
    // Implementation
}

2. Add Platform-Specific Implementations if needed in respective source sets:
   • androidMain/kotlin/.../MyNewComponent.android.kt
   • iosMain/kotlin/.../MyNewComponent.ios.kt
   • etc.
3. Add to SupportedComponents Enum in lumo-ui/plugin/src/main/java/com/nomanr/lumo/plugin/template/templateregistry/SupportedComponents.kt:

enum class SupportedComponents {
    Accordion,
    AlertDialog,
    // ... existing components
    MyNewComponent,  // Add here
}

4. Register in Template Registry:

SupportedComponents.MyNewComponent to Template(
    componentFiles = listOf("components/MyNewComponent.kt.template"),
    supportingFiles = listOf(/* any supporting files */),
    dependsOn = listOf(/* component dependencies */),
)

5. Create a Sample in sample-android/catalogue/ or sample-multiplatform/common/ showing usage
6. Test thoroughly across platforms
7. Submit PR - Templates will be generated automatically

​

Fixing a Bug

1. Identify the Issue:
   • Check if an issue exists on GitHub
   • If not, create one describing the bug
2. Locate the Bug:
   • Plugin bugs: lumo-ui/plugin/
   • Component bugs: lumo-ui/components-lab/
3. Fix and Test:
   • Make the fix
   • Add tests if applicable
   • Verify fix works in sample apps
4. Document the Fix:
   • Update CHANGELOG if needed
   • Reference issue number in commit
5. Submit PR:
   git commit -m "fix: resolve Button elevation issue (#123)"
   

​

Improving Documentation

1. Documentation is in the main website repository, not this one
2. For README or CONTRIBUTING.md changes in this repo:
   • Edit the markdown files directly
   • Preview your changes
   • Submit PR

​

Refactoring Code

1. Discuss First:
   • For large refactors, open an issue first
   • Explain the benefits
   • Get maintainer approval
2. Make Changes:
   • Keep PRs focused
   • Don’t mix refactoring with new features
   • Ensure all tests pass
3. Document:
   • Explain what changed and why
   • Update relevant documentation

​

Component Guidelines

​

Component Requirements

• Composable: Must be a @Composable function
• Customizable: Provide parameters for common customizations
• Themeable: Use theme colors and typography
• Accessible: Consider accessibility (content descriptions, etc.)
• Documented: Include KDoc comments
• Cross-platform: Work on all platforms (for multiplatform components)

​

Component Structure

package {{packageName}}

import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier

/**
 * A brief description of what the component does.
 *
 * @param modifier Modifier to be applied to the component
 * @param enabled Whether the component is enabled
 * @param onClick Callback when the component is clicked
 * ... other params
 */
@Composable
fun ComponentName(
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    onClick: () -> Unit,
    // More parameters...
) {
    // Implementation
}

/**
 * Defaults and additional variants
 */
object ComponentDefaults {
    // Default values, color schemes, etc.
}

​

Template Placeholders

• {{packageName}} - Replaced with user’s package name
• {{themeName}} - Replaced with user’s theme name

package {{packageName}}

@Composable
fun Button() {
    {{themeName}} {  // User's theme
        // Component content
    }
}

​

Testing Guidelines

​

Manual Testing Checklist

• Component renders correctly
• All parameters work as expected
• Theme integration works
• Works on all target platforms (for multiplatform)
• No compilation errors
• Code style is correct (./gradlew spotlessCheck)
• Sample app demonstrates the component
• Plugin generates the component correctly

​

Testing the Plugin

1. Publish locally:

./gradlew :lumo-ui:plugin:publishToMavenLocal

2. Test in a sample project:

./gradlew lumo --init
./gradlew lumo --add YourComponent

3. Verify generated files:
   • Check file locations
   • Verify placeholders are replaced
   • Ensure code compiles
   • Test the component works

​

Request for New Components

1. Go to https://github.com/nomanr/lumo-ui/issues
2. Click “New Issue”
3. Describe the component:
   • What it should do
   • How it should look
   • Examples from other libraries
   • Use cases
4. Add the component-request label
5. Wait for maintainer response

​

Pull Request Guidelines

​

Before Submitting

• Code follows project style (run ./gradlew spotlessApply)
• All existing tests pass
• New features include appropriate tests
• Commit messages are clear and descriptive
• PR description explains changes
• Breaking changes are clearly documented

​

PR Description Template

## Description
A clear description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Fixes #123

## Testing
How was this tested?

## Screenshots (if applicable)
Before/after screenshots for UI changes

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code where needed
- [ ] My changes generate no new warnings
- [ ] I have tested on relevant platforms

​

Review Process

1. Automated Checks:
   • Code style
   • Build success
   • Tests passing
2. Maintainer Review:
   • Code quality
   • Design decisions
   • Testing coverage
   • Documentation
3. Feedback:
   • Address review comments
   • Push updates to the same branch
   • Re-request review
4. Merge:
   • Once approved, maintainers will merge
   • Templates will be regenerated automatically
   • Changes will be in the next release

​

Building and Testing

​

Build the Project

# Full build
./gradlew build

# Build plugin only
./gradlew :lumo-ui:plugin:build

# Build components only
./gradlew :lumo-ui:components-lab:build

​

Run Tests

# Run all tests
./gradlew test

# Run plugin tests
./gradlew :lumo-ui:plugin:test

​

Clean Build

./gradlew clean build

​

Code of Conduct

• Be welcoming to new contributors
• Be respectful of differing opinions
• Focus on what is best for the project
• Show empathy towards other community members

​

Questions?

• General questions: Open a GitHub Discussion
• Bug reports: Open an issue
• Feature requests: Open an issue
• Security issues: Email [email protected]

​

License

​

Recognition

• GitHub contributors list
• Release notes (for significant contributions)
• Project README (for major contributions)

​

See Also

• Plugin API Reference
• Gradle Tasks Reference
• Configuration Properties Reference
• Troubleshooting Guide