Skip to content

Commit 975f0a3

Browse files
Mansi-mParticleMansi-mParticle
authored
docs: Updated readme file and add contributing and release file (#603)
1 parent 132eec9 commit 975f0a3

3 files changed

Lines changed: 188 additions & 1 deletion

File tree

‎CONTRIBUTING.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Contributing to mParticle Android SDK
2+
3+
Thanks for contributing! Please read this document to follow our conventions for contributing to the mParticle SDK.
4+
5+
6+
## Setting Up
7+
8+
1. Fork the repository and then clone down your fork
9+
2. Commit your code per the conventions below, and PR into the mParticle SDK main branch
10+
3. Your PR title will be checked automatically against the below convention (view the commit history to see examples of a proper commit/PR title). If it fails, you must update your title
11+
4. Our engineers will work with you to get your code change implemented once a PR is up
12+
13+
14+
## Development Process
15+
16+
1. Create your branch from `main`
17+
2. Make your changes
18+
3. Add tests for any new functionality
19+
4. Run the test suite to ensure tests (both new and old) all pass
20+
6. Update the documentation
21+
7. Create a Pull Request
22+
23+
24+
### Pull Requests
25+
26+
* Fill in the required template
27+
* Follow the [Android style guide](https://developer.android.com/kotlin/style-guide)
28+
* Include screenshots and animated GIFs in your pull request whenever possible
29+
* End all files with a newline
30+
31+
### PR Title and Commit Convention
32+
33+
PR titles should follow conventional commit standards. This helps automate the release process.
34+
35+
The standard format for commit messages is as follows:
36+
37+
```
38+
<type>[optional scope]: <description>
39+
40+
[optional body]
41+
42+
[optional footer]
43+
```
44+
45+
The following lists the different types allowed in the commit message:
46+
47+
- **feat**: A new feature (automatic minor release)
48+
- **fix**: A bug fix (automatic patch release)
49+
- **docs**: Documentation only changes
50+
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
51+
- **refactor**: A code change that neither fixes a bug nor adds a feature
52+
- **perf**: A code change that improves performance
53+
- **test**: Adding missing or correcting existing tests
54+
- **chore**: Changes that don't modify src or test files, such as automatic documentation generation, or building latest assets
55+
- **ci**: Changes to CI configuration files/scripts
56+
- **revert**: Revert commit
57+
- **build**: Changes that affect the build system or other dependencies
58+
59+
### Testing
60+
61+
We use JUnit and Mockito for our testing framework. Please write tests for new code you create. Before submitting your PR, ensure all tests pass by running:
62+
63+
#### Lint Checks
64+
```bash
65+
./gradlew lint
66+
```
67+
68+
#### Unit Tests
69+
```bash
70+
./gradlew test
71+
```
72+
73+
#### Instrumented Tests
74+
```bash
75+
./gradlew :android-core:cAT :android-kit-base:cAT --stacktrace
76+
```
77+
78+
Make sure all tests pass successfully before submitting your PR. If you encounter any test failures, investigate and fix the issues before proceeding.
79+
80+
81+
### Reporting Bugs
82+
83+
This section guides you through submitting a bug report for the mParticle Android SDK. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
84+
85+
To notify our team about an issue, please submit a ticket through our [mParticles support page](https://support.mparticle.com/hc/en-us/requests/new).
86+
87+
**When you are creating a ticket, please include as many details as possible:**
88+
89+
* Use a clear and descriptive title
90+
* Describe the exact steps which reproduce the problem
91+
* Provide specific examples to demonstrate the steps
92+
* Describe the behavior you observed after following the steps
93+
* Explain which behavior you expected to see instead and why
94+
* Include logcat output and stack traces if applicable
95+
* Include your SDK version and Android OS version
96+
97+
98+
## License
99+
100+
By contributing to the mParticle Android SDK, you agree that your contributions will be licensed under its [Apache License 2.0](LICENSE).

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
<img src="https://static.mparticle.com/sdk/mp_logo_black.svg" width="280">
22

3-
## Android SDK
3+
# Android SDK
44

55
[![Maven Central Status](https://maven-badges.herokuapp.com/maven-central/com.mparticle/android-core/badge.svg?style=flat-square)](https://search.maven.org/#search%7Cga%7C1%7Cmparticle)
66

7+
A single SDK to collect analytics data and send it to 100+ marketing, analytics, and data platforms. Simplify your data integration with a single API.
8+
79
Hello! This is the public repo of the mParticle Android SDK. mParticle's mission is straightforward: make it really easy to use all of the great services in the app ecosystem. Our SDKs and platform are designed to be your abstraction layer and data hub, and we do the work of integrating with each individual app service so you don't have to.
810

911
The platform has grown to support 100+ partners in the ecosystem, including developer tools, analytics, attribution, marketing automation, and advertising services. We also have a powerful audience engine that sits atop our platform to let you action on all of your data - [learn more here](https://www.mparticle.com)!
@@ -278,6 +280,10 @@ Just by initializing the SDK you'll be set up to track user installs, engagement
278280
* [SDK Documentation](https://docs.mparticle.com/developers/sdk/android/)
279281
* [Javadocs](http://docs.mparticle.com/developers/sdk/android/javadocs/index.html)
280282

283+
## Contributing
284+
285+
We welcome contributions! If you're interested in contributing to the mParticle Android SDK, please read our [Contributing Guidelines](CONTRIBUTING.md).
286+
281287
## License
282288

283289
[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)

‎RELEASE.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Release Process
2+
3+
This document outlines the process for releasing the mParticle Android SDK and its kits.
4+
5+
## Step 1: Preparing the SDK for Release
6+
7+
The Android SDK and kits are released using GitHub Actions. The SDK and kits are currently coupled together in the release process.
8+
9+
### Pre-release Checklist
10+
- Ensure all commits are in the public main branch
11+
- Review `release.yml` in the repo for specific workflow details
12+
- The release job deploys the most current snapshot of main branch release tag to main branch
13+
14+
15+
## Step 2: Release via GitHub Actions
16+
17+
### What the GitHub Release Job Does
18+
19+
1. **Initial Setup**
20+
- Verifies job is running from public repo and on main branch
21+
- Creates temporary `release/{run_number}` branch
22+
23+
2. **Testing Phase**
24+
- Runs unit and instrumented tests in parallel
25+
- Instrumented tests require an emulator
26+
- Unit tests run independently
27+
- Updates kits and runs additional tests
28+
29+
3. **Version Management**
30+
- Runs semantic version action
31+
- Automatically bumps `build.gradle` version based on commit messages
32+
- No version bump if no new commits (e.g., feat/fix)
33+
- Generates release notes automatically
34+
- Requires linear history between development and main branches
35+
36+
4. **Artifact Publishing**
37+
- Uploads artifacts to Sonatype (core and kits)
38+
- Builds and signs the core SDK and all kit artifacts
39+
- Uploads to Sonatype Nexus (staging area)
40+
- Syncs artifacts to Maven Central
41+
> Note: This step will be moved before version bump during semantic release
42+
43+
5. **Branch Synchronization**
44+
- Pushes release branch to:
45+
- Public main branch
46+
- Public development branch
47+
- Internal repo main branch
48+
- Deletes release branch on success (preserved on failure for debugging)
49+
50+
### How to Release
51+
52+
1. Navigate to the Actions tab
53+
2. Select "release SDK"
54+
3. Run the workflow from main branch with "true" first to perform a dry run
55+
> Important: Always start with a dry run to validate the release process. This will perform all steps up to semantic release without actually publishing, helping catch potential issues early.
56+
4. If the dry run succeeds, run the workflow again with "false" option to perform the actual release
57+
> Note: Only proceed with the actual release after confirming a successful dry run
58+
59+
### Important Notes
60+
61+
- **Release Duration**: Expect ~20 minutes due to comprehensive test suite
62+
- **Emulator Issues**:
63+
- Sometimes GitHub Actions emulators fail
64+
- We have a custom script to install and start the emulator `scripts/install-start-emulator.sh`
65+
- OS version is hardcoded to avoid issues with new releases
66+
- **Code Reusability**:
67+
- Reusable GitHub Actions are defined in the [mparticle-workflows repo](https://github.com/mParticle/mparticle-workflows)
68+
- This enables other platforms to reuse similar jobs
69+
70+
## Post-Release Verification
71+
72+
After a successful build through GitHub Actions, verify:
73+
1. Public repo has a new semantic release tag
74+
2. New artifact is present in [Sonatype](https://central.sonatype.com/publishing)
75+
76+
## Troubleshooting
77+
78+
If you encounter emulator issues during testing, check:
79+
- [Emulator setup script](https://github.com/mParticle/mparticle-android-sdk/blob/main/scripts/install-start-emulator.sh)
80+
- Current OS version compatibility
81+
- GitHub Actions logs for specific error messages

0 commit comments

Comments
 (0)