Skip to content

Commit 1244aec

Browse files
Mansi-mParticleMansi-mParticle
authored
docs: Updated readme file and add contributing and release file (#430)
1 parent 273bd70 commit 1244aec

File tree

3 files changed

+172
-0
lines changed

3 files changed

+172
-0
lines changed

‎CONTRIBUTING.md‎

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

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
# mParticle Apple SDK
44

5+
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.
6+
57
This is the mParticle Apple SDK for iOS and tvOS.
68

79
At mParticle our mission is straightforward: make it really easy for apps and app services to connect and allow you to take ownership of your 1st party data.
@@ -232,6 +234,10 @@ Just by initializing the SDK you'll be set up to track user installs, engagement
232234

233235
- [SDK Documentation](http://docs.mparticle.com/#mobile-sdk-guide)
234236

237+
## Contributing
238+
239+
We welcome contributions! If you're interested in contributing to the mParticle Apple SDK, please read our [Contributing Guidelines](CONTRIBUTING.md).
240+
235241
## Support
236242

237243
Questions? Have an issue? Read the [docs](https://docs.mparticle.com/developers/sdk/ios/) or contact our **Customer Success** team at <support@mparticle.com>.

‎RELEASE.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Release Process
2+
3+
This document outlines the process for creating a new release of the mParticle Apple SDK.
4+
5+
## Automated Release Process
6+
7+
We use GitHub Actions to automate our release process. Follow these steps to create a new release:
8+
9+
### Pre-release Checklist
10+
- Ensure all commits are in the public main branch
11+
- Review `sdk-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+
## Step 2: Release via GitHub Actions
15+
16+
### What the GitHub Release Job Does
17+
18+
1. **Initial Setup**
19+
- Verifies job is running from public repo and on main branch
20+
- Creates temporary `release/{run_number}` branch
21+
22+
2. **Testing Phase**
23+
- Runs unit tests for iOS and tvOS platforms
24+
- Validates CocoaPods spec
25+
- Validates Swift Package Manager build
26+
- Updates kits and runs additional tests
27+
28+
3. **Version Management**
29+
- Runs semantic version action
30+
- Automatically bumps version based on commit messages
31+
- No version bump if no new commits (e.g., feat/fix)
32+
- Generates release notes automatically
33+
34+
4. **Artifact Publishing**
35+
- Publishes to package managers:
36+
- Pushes to CocoaPods trunk
37+
- Updates Swift Package Manager
38+
- Creates GitHub release with artifacts
39+
40+
41+
42+
### How to Release
43+
44+
1. Navigate to the Actions tab in GitHub
45+
2. Select "iOS SDK Release" workflow
46+
3. Run the workflow from main branch with "true" first to perform a dry run
47+
> 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.
48+
4. If the dry run succeeds, run the workflow again with "false" option to perform the actual release
49+
> Note: Only proceed with the actual release after confirming a successful dry run
50+
51+
### Important Notes
52+
53+
- **Release Duration**: Expect ~30 minutes due to comprehensive test suite across platforms
54+
- **Platform Requirements**:
55+
- Tests run on macOS runners
56+
- Multiple Xcode versions may be tested
57+
- Both iOS and tvOS platforms are validated
58+
- **Code Reusability**:
59+
- Reusable GitHub Actions are defined in the [mparticle-workflows repo](https://github.com/mParticle/mparticle-workflows)
60+
- This enables other platforms to reuse similar jobs
61+
62+
## Post-Release Verification
63+
64+
After a successful build through GitHub Actions, verify:
65+
1. Public repo has a new semantic release tag
66+
2. New version is available on:
67+
- [CocoaPods](https://cocoapods.org/pods/mParticle-Apple-SDK)
68+
- Swift Package Manager
69+
70+
## Troubleshooting
71+
72+
If you encounter issues during testing, check:
73+
- Xcode version compatibility
74+
- Platform-specific test failures (iOS vs tvOS)
75+
- GitHub Actions logs for specific error messages
76+
- CocoaPods trunk status

0 commit comments

Comments
 (0)