Pull requests are welcome on the master branch.
We know making you first pull request can be scary. If you have trouble with any of the contribution rules, still make the Pull Request. We are here to help.
We personally think the best way to get started contributing to this library is by using it in one of your projects!
We follow the Ray Wenderlich Style Guide very closely with the following exception:
- Use the Xcode default of 4 spaces for indentation.
SwiftLint runs automatically on all pull requests via houndci.com. If you have SwiftLint installed, you will receive the same warnings in Xcode at build time, that hound will check for on pull requests.
Function body lengths in tests will often cause a SwiftLint warning. These can be handled on a per case bases by prefixing the function with:
// swiftlint:disable function_body_length
func someFunctionThatShouldHaveAReallyLongBody() {}Common violations to look out for are trailing white and valid docs.
All code going into master requires testing. We keep code coverage at 100% to ensure the best possibility that all edge cases are tested for. It's good practice to test for any variations that can cause nil to be returned.
Tests are run in Travis CI automatically on all pull requests, branches and tags. These are the same tests that run in Xcode at development time.
-
Readable code should be preferred over commented code.
Comments in code are used to document non-obvious use cases. For example, when the use of a piece of code looks unnecessary, and naming alone does not convey why it is required.
-
Comments need to be updated or removed if the code changes.
If a comment is included, it is just as important as code and has the same technical debt weight. The only thing worse than a unneeded comment is a comment that is not maintained.
Code documentation is different from comments. Please be liberal with code docs.
When writing code docs, remember they are:
- Displayed to a user in Xcode quick help
- Used to generate API documentation
- API documentation also generates Dash docsets
In particular paying attention to:
- Keeping docs current
- Documenting all parameters and return types (SwiftLint helps with warning when they are not valid)
- Stating common issues that a user may run into
See NSHipster Swift Documentation for a good reference on writing documentation in Swift.
You're always welcome to open Pull Requests, even if the result is not quite finished or you need feedback!
Here's a checklist for you about what makes Pull Requests to ReSwift shine:
- Run SwiftLint locally to ensure your code-style is consistent with the rest of the codebase.
- Keep your Pull Requests focused. Rather be opening multiple PRs than making a dozen unrelated but discussion worthy changes in a single PR.
- You can propose PRs to merge with the
masterbranch directly. We don't use any complex branching strategies.
As a contributor, choose the "squash & merge" strategy to merge PRs with a single commit, keeping the commit history clean. (That's an upside of focused Pull Requests: you don't lose extra information.)
Members of the @ReSwift/releases team have the necessary permissions to publish a new version to CocoaPods. If you want a new version of ReSwift-Thunk to be published you should ping these folks.
To create a new release, create a pull request targeting either master, or a separate release branch for hot-fixes, with the following:
- Bump version number in
ReSwift-Thunk.podspecandInfo.plist(We follow semver - most importantly any breaking API change should result in a major API version bump) - Add the new version number and the release date to
CHANGELOG.md - Create a tag off of the relevant branch (
masterfor regular release) and add the relevant changelog entries to the release list on GitHub - Publish the new version to the CocoaPods trunk