Contributing to ReSwift

Some design decisions for the core of ReSwift are still up in the air (see issues), there’s lots of useful documentation that can be written and a ton of extensions and tools are waiting to be built on top of ReSwift.

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!

Swift style guide

We follow the Ray Wenderlich Style Guide very closely with the following exception:

  • Use the Xcode default of 4 spaces for indentation.

SwiftLint

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.

Tests

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.

Comments

  • 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

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.

Generating documentation

The documentation at reswift.github.io/ReSwift is generated from by combining the Markdown documentation files with generated documentation using jazzy.

The Markdown files used to generated documentation are:

  • README.md
  • CONTRIBUTING.md
  • CHANGELOG.md
  • LICENSE.md
  • Docs/
    • Getting Started Guide.md
    • templates/
      • heading.md
      • toc.md

Along with the Documentation sections, API sections also support extra documentation found in:

  • Docs/
    • Actions.md
    • Reducers.md
    • State.md
    • Stores.md
    • Utilities.md

Each of the Markdown files are processed by the generate_docs.sh script and saved into Docs/tmp/ ready for jazzy to generate the final documentation.

The processing of each file can include:

  • Extracting a single section (ie, for splitting up README.md)
  • Adding a title
  • Replacing {{version}} with the current version
  • Ad-hoc string replacements (found in .jazzy.json under “string-replacements”)

The documentation is hosted by GitHub pages under the ReSwift gh-pages branch. The build.sh script in the gh-pages branch, installs / updates jazzy, checks out the latest master branch of ReSwift, and calls the generated_docs.sh script to generate docs into the master folder. Docs changes can then be committed and pushed to the gh-pages branch.

The custom jazzy theme is located in: Docs/jazzy-theme.

Changes to generate_docs.sh will generally only be needed when sections / files are added or removed.

Documentation TL;DR

To generate docs locally:

./generate_docs.sh # -> Output to doc_output

To update the GitHub pages documentation:

git clone https://github.com/ReSwift/ReSwift.git --branch gh-pages ReSwift-gh-pages
cd ReSwift-gh-pages
./build.sh
# Documentation is ready to be committed.

Pull Request Technicalities

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 master branch 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.)

Publishing New Releases

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 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.podspec and Info.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 (master for regular release) and add the relevant changelog entries to the release list on GitHub

  • [ ] Attach a Carthage-built binary release.

    With .xcframeworks carthage archive doesn’t work anymore, so you need to zip the whole clean build folder:

    $ rm -rf Carthage/
$ carthage build --no-skip-current --use-xcframeworks
$ ditto -c -k --sequesterRsrc --keepParent Carthage ReSwift.framework.zip

    Note that the naming convention of .framework.zip doesn’t change. Otherwise, Carthage won’t recognize the binary.

  • [ ] Publish the new version to the CocoaPods trunk

  • [ ] ✨✨Bonus points ✨✨: for major versionReSwift releases, update ReSwiftRouter and GitHubBrowserExample to use the latest version of ReSwift