All changes, no matter how trivial, must be done via pull request. Commits
should never be made directly on the main
branch. Prefer rebasing over
merging main
into your PR branch to update it and resolve conflicts.
If you have commit access to SwiftLint and believe your change to be trivial and not worth waiting for review, you may open a pull request and merge immediately, but this should be the exception, not the norm.
git clone https://github.com/realm/SwiftLint.git
cd SwiftLint
xed .
- Select the "swiftlint" scheme
cmd-opt-r
open the scheme options- Set the "Arguments Passed On Launch" you want in the "Arguments" tab. See available arguments in the README.
- Set the "Working Directory" in the "Options" tab to the path where you would like to execute SwiftLint. A folder that contains swift source files.
- Hit "Run"
Arguments | Options |
---|---|
Then you can use the full power of Xcode/LLDB/Instruments to develop and debug your changes to SwiftLint.
git clone https://github.com/realm/SwiftLint.git
cd SwiftLint
swift build [-c release]
- Use the produced
swiftlint
binary from the command line, either by runningswift run [-c release] [swiftlint] [arguments]
or by invoking the binary directly at.build/[release|debug]/swiftlint
- [Optional] Attach LLDB:
lldb -- .build/[release|debug]/swiftlint [arguments]
If XCTest cases or functions are added/removed/renamed, or if rules are
added/removed/renamed, you'll need to run make sourcery
, which requires that
Sourcery be installed on your
machine. This will update source files to reflect these changes.
SwiftLint supports building via Xcode and Swift Package Manager on macOS, and with Swift Package Manager on Linux. When contributing code changes, please ensure that all three supported build methods continue to work and pass tests.
$ xcodebuild -scheme swiftlint test
$ swift test
$ make docker_test
New rules should be added in the Source/SwiftLintFramework/Rules
directory.
Rules should conform to either the Rule
or ASTRule
protocols.
All new rules or changes to existing rules should be accompanied by unit tests.
Whenever possible, prefer adding tests via the triggeringExamples
and
nonTriggeringExamples
properties of a rule's description
rather than adding
those test cases in the unit tests directly. This makes it easier to understand
what rules do by reading their source, and simplifies adding more test cases
over time. This way adding a unit test for your new Rule is just a matter of
adding a test case in RulesTests.swift
which simply calls
verifyRule(YourNewRule.description)
.
For debugging purposes examples can be marked as focused
. If there are any
focused examples found, then only those will be run when running tests for that rule.
nonTriggeringExamples: [
Example("let x: [Int]"),
Example("let x: [Int: String]").focused() // only this one will be run in tests
],
triggeringExamples: [
Example("let x: ↓Array<String>"),
Example("let x: ↓Dictionary<Int, String>")
]
If your rule supports user-configurable options via .swiftlint.yml
, you can
accomplish this by conforming to ConfigurationProviderRule
. You must provide a
configuration object via the configuration
property:
- The object provided must conform to
RuleConfiguration
. - There are several provided
RuleConfiguration
s that cover the common patterns like configuring violation severity, violation severity levels, and evaluating names. - If none of the provided
RuleConfiguration
s are applicable, you can create one specifically for your rule.
See ForceCastRule
for a rule that allows severity configuration,
FileLengthRule
for a rule that has multiple severity levels,
IdentifierNameRule
for a rule that allows name evaluation configuration:
force_cast: warning
file_length:
warning: 800
error: 1200
identifier_name:
min_length:
warning: 3
error: 2
max_length: 20
excluded: id
If your rule is configurable, but does not fit the pattern of
ConfigurationProviderRule
, you can conform directly to Rule
:
init(configuration: AnyObject) throws
will be passed the result of parsing the value from.swiftlint.yml
associated with your rule'sidentifier
as a key (if present).configuration
may be of any type supported by YAML (e.g.Int
,String
,Array
,Dictionary
, etc.).- This initializer must throw if it does not understand the configuration, or it cannot be fully initialized with the configuration and default values.
- By convention, a failing initializer throws
ConfigurationError.UnknownConfiguration
. - If this initializer fails, your rule will be initialized with its default
values by calling
init()
.
All changes should be made via pull requests on GitHub.
When issuing a pull request with user-facing changes, please add a
summary of your changes to the CHANGELOG.md
file.
We follow the same syntax as CocoaPods' CHANGELOG.md:
- One Markdown unnumbered list item describing the change.
- 2 trailing spaces on the last line describing the change (so that Markdown renders each change on its own line).
- A list of Markdown hyperlinks to the contributors to the change. One entry per line. Usually just one.
- A list of Markdown hyperlinks to the issues the change addresses. One entry per line. Usually just one. If there was no issue tracking this change, you may instead link to the change's pull request.
- All CHANGELOG.md content is hard-wrapped at 80 characters.
SwiftLint uses Azure Pipelines for most of its CI jobs, primarily because they're the only CI provider to have a free tier with 10x concurrency on macOS.
Some CI jobs run in GitHub Actions (e.g. Docker).
Some CI jobs run on Buildkite using Mac Minis from MacStadium. These are jobs that benefit from being run on the latest Xcode & macOS versions on bare metal.
To bring up a new Buildkite worker from MacStadium:
- Change account password
- Update macOS to the latest version
- Install Homebrew: https://brew.sh
- Install Buildkite agent and other tools via Homebrew:
brew install aria2 bazelisk htop buildkite/buildkite/buildkite-agent robotsandpencils/made/xcodes
- Install latest Xcode version:
xcodes update && xcodes install 14.0.0
- Add
DANGER_GITHUB_API_TOKEN
andHOME
to/opt/homebrew/etc/buildkite-agent/hooks/environment
- Configure and launch buildkite agent:
brew info buildkite-agent
/ https://buildkite.com/organizations/swiftlint/agents#setup-macos