Contributing

​

Getting Started

1. Familiarize yourself with the SDK by reading the documentation
2. Set up your development environment by following the Building from Source guide
3. Review the project’s architecture and code structure
4. Check the GitHub Issues for open items you can work on

​

Ways to Contribute

​

Report Bugs

1. Check if the issue has already been reported in GitHub Issues
2. If not, create a new issue with:
   • A clear, descriptive title
   • Steps to reproduce the problem
   • Expected vs actual behavior
   • SDK version, platform (Android/iOS), and OS version
   • Code samples or screenshots if applicable

​

Request Features

1. Check existing issues and pull requests to avoid duplicates
2. Create a new issue describing:
   • The problem the feature would solve
   • How you envision the feature working
   • Any alternative solutions you’ve considered

​

Improve Documentation

• Fix typos, grammar, or unclear explanations
• Add examples or tutorials
• Improve API documentation
• Translate documentation

​

Submit Code

1. Fork the repository
2. Create a feature branch from master
3. Make your changes
4. Test thoroughly on both platforms if applicable
5. Submit a pull request

​

Development Workflow

​

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/maps-core.git
cd maps-core
git submodule init
git submodule update

​

2. Create a Branch

git checkout -b feature/your-feature-name

• feature/feature-name for new features
• fix/bug-description for bug fixes
• docs/what-changed for documentation
• refactor/what-changed for refactoring

​

3. Make Changes

​

Code Style Guidelines

• Follow the existing naming conventions (camelCase for variables/functions, PascalCase for classes)
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions focused and concise

• Follow Kotlin coding conventions
• Use meaningful naming
• Leverage Kotlin’s language features appropriately

• Follow Swift API Design Guidelines
• Use Swift’s modern features
• Maintain consistency with existing code

​

4. Test Your Changes

cd android
./gradlew test
./gradlew connectedAndroidTest

swift test

• Create a sample app that uses your changes
• Test on real devices, not just simulators/emulators
• Test different OS versions if relevant
• Test edge cases and error conditions

​

5. Commit Your Changes

git add .
git commit -m "Add support for animated polygon fills

- Implement animation system for polygon layers
- Add new PolygonAnimationStyle class
- Update documentation with examples
- Add unit tests for animation timing"

• Use the present tense (“Add feature” not “Added feature”)
• First line is a summary (50 characters or less)
• Add a blank line, then a detailed description if needed
• Reference issue numbers when applicable (“Fixes #123”)

​

6. Update Documentation

• Update code comments and inline documentation
• Update relevant markdown documentation files
• Add examples showing how to use the new feature
• Update the changelog if appropriate

​

7. Submit a Pull Request

git push origin feature/your-feature-name

1. Go to the repository
2. Click “New Pull Request”
3. Select your fork and branch
4. Fill in the PR template with:
   • Description of changes
   • Related issue numbers
   • Testing performed
   • Screenshots (if UI changes)
   • Breaking changes (if any)

​

Pull Request Guidelines

​

Before Submitting

• Code builds successfully on all affected platforms
• All tests pass
• New code has appropriate test coverage
• Documentation is updated
• Commit messages are clear and descriptive
• Code follows the project’s style guidelines
• No unnecessary files are included (build artifacts, IDE configs)

​

After Submitting

• Respond to review comments promptly
• Make requested changes in new commits (don’t force-push)
• Update the PR description if the scope changes
• Be patient - reviews may take time

​

Modifying Djinni Interfaces

1. Modify the .djinni files in the djinni/ directory
2. Regenerate the bindings:
   cd djinni
   make clean djinni
   
3. Implement the changes on both platforms
4. Update documentation to reflect API changes
5. Test thoroughly on both platforms

​

Platform-Specific Contributions

​

Android Contributions

• Ensure compatibility with Android 8.0+ (API level 26+)
• Test on devices with different screen densities
• Consider performance on lower-end devices
• Follow Material Design guidelines for UI components
• Keep minimum SDK and dependency versions in mind

​

iOS Contributions

• Ensure compatibility with iOS 14+
• Test on both iPhone and iPad if relevant
• Consider both UIKit and SwiftUI integration
• Follow Apple’s Human Interface Guidelines
• Test on different screen sizes and orientations

​

C++ Core Contributions

• Ensure cross-platform compatibility
• Use C++17 standard features
• Avoid platform-specific APIs in the core
• Consider performance implications
• Test on both Android (OpenGL) and iOS (Metal) rendering paths

​

Code Review Process

1. Automated Checks: CI/CD runs tests and builds
2. Maintainer Review: A maintainer reviews your code
3. Feedback: You may receive feedback or change requests
4. Iteration: Make requested changes and push updates
5. Approval: Once approved, your PR will be merged

​

Reporting Security Issues

1. Email the maintainers privately (check the repository for contact information)
2. Provide details about the vulnerability
3. Give reasonable time for a fix before public disclosure

​

License

• You have the right to submit the code
• Your contribution doesn’t include copyrighted material from others
• You understand the implications of the MPL 2.0 license

​

Community Guidelines

• Be welcoming to newcomers
• Be respectful of differing viewpoints
• Accept constructive criticism gracefully
• Focus on what’s best for the community
• Show empathy towards other community members

​

Getting Help

• Check the documentation
• Ask questions in your pull request
• Look for similar issues or PRs
• Review the architecture documentation

​

Recognition

• The project’s commit history
• Pull request acknowledgments
• Release notes (for significant contributions)