Swift Driver Development Guide
Index
- Things to Install
- The Code
- Building
- Running Tests
- Writing and Generating Documentation
- Linting and Style
- Workflow
- Code Review
- Resources
Things to install
- swiftenv: a command-line tool that allows easy installation of and switching between versions of Swift.
- Use this to install Swift 4.2 and Swift 5.0.
- Jazzy: the tool we use to generate documentation.
- SwiftLint: the Swift linter we use.
- Sourcery: the tool we use to generate lists of test names (required to run the tests on Linux).
- libmongoc: the MongoDB C driver, which this library wraps. See the installation instructions provided in our README or on the libmongoc docs.
If you are using (Vim/Neovim)
- swift.vim: A fork of Keith Smiley’s
swift.vim
with fixed indenting rules. This adds proper indenting and syntax for Swift to Vim. This fork also provides a match rule for column width highlighting.- Please read the NOTICE for proper credits.
The code
You should clone this repository, as well as the MongoDB Driver specifications. Since this library wraps the MongoDB C Driver, we also recommend cloning mongodb/mongo-c-driver so you have the source code and documentation easily accessible.
Building
From the Command line
Run swift build
or simply make
in the project’s root directory.
In Xcode
We do not provide or maintain an already-generated .xcodeproj
in our repository. Instead, you must generate it locally.
To generate the .xcodeproj
file:
- Install the Ruby gem
xcodeproj
withgem install xcodeproj
(you may need tosudo
) - Run
make project
- You’re ready to go! Open
MongoSwift.xcodeproj
and build and test as normal.
Why is this necessary? The project requires a customized copy resources
build phase to include various test .json
files. By default, this phase is not included when you run swift package generate-xcodeproj
. So make project
first generates the project, and then uses xcodeproj
to manually add the files to the appropriate targets (see add_json_files.rb
).
Running Tests
NOTE: Several of the tests require a mongod instance to be running on the default host/port, localhost:27017
. (You can start this by simply running mongod
.)
You can run tests from Xcode as usual. If you prefer to test from the command line, keep reading.
From the Command Line
We recommend installing the ruby gem xcpretty
and running tests by executing make test-pretty
, as this provides output in a much more readable format. (Works on MacOS only.)
Alternatively, you can just run the tests with swift test
, or make test
.
To filter tests by regular expression:
- If you are using
swift test
, provide the--filter
argument: for example,swift test --filter=MongoClientTests
. - If you are using
make test
ormake test-pretty
, provide theFILTER
environment variable: for example,make test-pretty FILTER=MongoCollectionTests
.
Diagnosing Backtraces on Linux
SWIFT-755 documents an outstanding problem on Linux where backtraces do not contain debug symbols. As discussed in this Stack Overflow thread, a symbolicate-linux-fatal
script may be used to add symbols to an existing backtrace. Consider the following:
$ swift test --filter CrashingTest &> crash.log
$ symbolicate-linux-fatal /path/to/MongoSwiftPackageTests.xctest crash.log
This will require you to manually provide the path to the compiled test binary (e.g. .build/x86_64-unknown-linux/debug/MongoSwiftPackageTests.xctest
).
Writing and Generating Documentation
We document new code as we write it. We use C-style documentation blocks (/** ... */
) for documentation longer than 3 lines, and triple-slash (///
) for shorter documentation.
Comments that are not documentation should use two slashes (//
).
Documentation comments should generally be complete sentences and should end with periods.
Our documentation site is automatically generated from the source code using Jazzy. We regenerate it each time we release a new version of the driver.
To regenerate the files, run make documentation
from the project’s root directory. You can then inspect the changes to the site by opening the files in /docs
in your web browser.
Linting and Style
We use SwiftLint for linting. You can see our configuration in the .swiftlint.yml
file in the project’s root directory. Run swiftlint
in the /Sources
directory to lint all of our files. Running swiftlint autocorrect
will correct some types of violations.
For style guidance, look at Swift’s API design guidelines and Google’s Swift Style Guide.
Sublime Text Setup
If you use Sublime Text, you can get linting violations shown in the editor by installing the packages SublimeLinter and SublimeLinter-contrib-swiftlint.
Vim/Neovim Setup
If you use Vim or Neovim, then you can get linting support by using ale
by w0rp
. This will show symbols in the gutter for warnings/errors and show linter messages in the status.
Workflow
- Create a feature branch, named by the corresponding JIRA ticket if exists, along with a short descriptor of the work: for example,
SWIFT-30/writeconcern
. - Do your work on the branch.
- If you add, remove, or rename any tests, make sure to update
LinuxMain.swift
accordingly. If you are on MacOS, you can do that by runningmake sourcery
. - Make sure your code builds and passes all tests on Travis. Every time you push to GitHub or open a pull request, it will trigger a new build.
- Open a pull request on the repository. Make sure you have rebased your branch onto the latest commits on
master
. - Go through code review to get the team’s approval on your changes. (See the next section on Code Review for more details on this process.)
Once you get the required approvals and your code passes all tests:
- Rebase on master again if needed.
- Build and rerun tests.
- Squash all commits into a single, descriptive commit method, formatted as:
TICKET-NUMBER: Description of changes
. For example,SWIFT-30: Implement WriteConcern type
. - Merge it, or if you don’t have permissions, ask someone to merge it for you.
Code Review
Giving a review
When giving a review, please batch your comments together to cut down on the number of emails sent to others involved in the pull request. You can do this by going to the Files Changed
tab. When you post your first comment, press Start a review
. When you’re done commenting, click Finish your review
(top right).
Please feel free to leave reviews on your own code when you open a pull request in order add additional context, point out an aspect of the design you’re unsure of, etc.
Responding to a review
You can use the same batching approach as above to respond to review comments. Once you’ve posted your responses and pushed new commits addressing the comments, re-request reviews from your reviewers by clicking the arrow circle icons next to their names on the list of reviewers.
Note: GitHub allows marking comment threads on pull requests as resolved
, which hides them from view. Always allow the original commenter to resolve a conversation. This allows them to verify that your changes match what they requested before the conversation is hidden.
Resources
Swift
- A Swift Introduction to Swift - talk by Kaitlin
- Swift Language Guide
- Swift Standard Library docs
- Swift’s Encoder and Decoder Protocols - talk by Kaitlin