Skip to content

Commit c10c9b8

Browse files
federicobucchifedericobucchi
authored
Add Contributing.md (#2978)
motivation: Quick start contribution guide for Swift Package Manager. Changes: * Add Documentation/Contributing.md * Add SwiftFormat and patch size / number of commits info * Add ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md * Consolidate between Contributing.md and the content in https://github.com/apple/swift-package- manager/blob/main/Documentation/Development.md and remove Development.md * Update Contributions section in main README.md * Replace the link for contributing on https://github.com/apple/swift-package-manager#contributions to point to the new Contributing.md rdar://problem/70187482
1 parent ebc47e1 commit c10c9b8

File tree

6 files changed

+330
-216
lines changed

6 files changed

+330
-216
lines changed

‎.github/ISSUE_TEMPLATE.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
### Expected behavior
2+
_[what you expected to happen]_
3+
4+
### Actual behavior
5+
_[what actually happened]_
6+
7+
### Steps to reproduce
8+
9+
1. ...
10+
2. ...
11+
12+
### If possible, minimal yet complete reproducer code (or URL to code)
13+
14+
_[anything to help us reproducing the issue]_
15+
16+
### Swift Package Manager version/commit hash
17+
18+
_[the Swift Package Manager tag/commit hash]_
19+
20+
### Swift & OS version (output of `swift --version && uname -a`)

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
_[One line description of your change]_
2+
3+
### Motivation:
4+
5+
_[Explain here the context, and why you're making that change. What is the problem you're trying to solve.]_
6+
7+
### Modifications:
8+
9+
_[Describe the modifications you've done.]_
10+
11+
### Result:
12+
13+
_[After your change, what will change.]_

‎Documentation/Contributing.md

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# Contributing to Swift Package Manager
2+
There are several types of contributions one can make. Bug fixes, documentation and enhancements that do not materially change the user facing semantics of Swift Package Manager should be submitted directly as PR.
3+
4+
Larger changes that do materially change the semantics of Swift Package Manager (e.g. changes to the manifest format or behavior) are required to go through [Swift Evolution Process](https://github.com/apple/swift-evolution/blob/master/process.md).
5+
6+
To see how previous evolution decisions for SwiftPM have been made and have some direction for the development of future features please check out the [Community Proposals](https://forums.swift.org/tag/packagemanager).
7+
8+
For more information about making contributions to the Swift project in general see [Swift Contribution Guide](https://swift.org/contributing/).
9+
10+
## Reporting issues
11+
* [SwiftPM JIRA Bug Tracker](https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22).
12+
* [Guide for filing quality bug reports](https://github.com/apple/swift-package-manager/blob/main/Documentation/Resources.md#reporting-a-good-swiftpm-bug).
13+
14+
## Development environment
15+
16+
First, clone a copy of SwiftPM code from https://github.com/apple/swift-package-manager.
17+
18+
If you are preparing to make a contribution you should fork the repository first and clone the fork which will make opening Pull Requests easier. See "Creating Pull Requests" section below.
19+
20+
SwiftPM is typically built with a pre-existing version of SwiftPM present on the system, but there are multiple ways to setup your development environment:
21+
22+
### Using Xcode (Easiest)
23+
24+
1. Install Xcode from [https://developer.apple.com/xcode](https://developer.apple.com/xcode) (including betas!).
25+
2. Verify the expected version of Xcode was installed.
26+
3. Open SwiftPM's `Package.swift` manifest with Xcode, and use Xcode to edit the code, build, and run the tests.
27+
28+
### Using the Command Line
29+
30+
If you are using macOS and have Xcode installed, you can use the command line even without downloading and installing a toolchain, otherwise, you first need to doownload and install one.
31+
32+
#### Installing the toolchain
33+
34+
1. Download a toolchain from https://swift.org/download/
35+
2. Install it and verify the expected version of the toolchain was installed:
36+
37+
**macOS**
38+
```bash
39+
$> export TOOLCHAINS=swift
40+
```
41+
42+
Verify that we're able to find the swift compiler from the installed toolchain.
43+
```bash
44+
$> xcrun --find swift
45+
/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/swift
46+
$> swift package --version
47+
Swift Package Manager - Swift 5.3.0
48+
$> swift --version
49+
Apple Swift version 5.3
50+
```
51+
52+
**Linux**
53+
```bash
54+
$> export PATH=/path/to/swift-toolchain/usr/bin:"${PATH}"
55+
```
56+
Verify that we're able to find the swift compiler from the installed toolchain.
57+
```bash
58+
$> which swift
59+
/path/to/swift-toolchain/usr/bin/swift
60+
$> swift package --version
61+
Swift Package Manager - Swift 5.3.0
62+
$> swift --version
63+
Apple Swift version 5.3
64+
```
65+
66+
Note: Alternatively use tools like [swiftenv](https://github.com/kylef/swiftenv) that help manage toolchains versions.
67+
68+
#### Building
69+
70+
```bash
71+
$> swift build
72+
```
73+
74+
A successful build will create a `.build/` directory with the following approximate structure:
75+
```bash
76+
artifacts/
77+
checkouts/
78+
debug/
79+
repositories
80+
x86_64-apple-macosx
81+
```
82+
83+
Binary artifacts are located in `x86_64-apple-macosx/` when building on macOS,
84+
or the equivalent on other architectures and operating systems.
85+
86+
These binaries can be used to test the code modification. For example, to test the `swift package init` and `swift build` commands from the new SwiftPM artifacts in `.build/`:
87+
88+
```bash
89+
$> cd /tmp && mkdir hello && cd hello
90+
$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-package init
91+
$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-build
92+
```
93+
94+
#### Testing
95+
96+
```bash
97+
$> swift test
98+
```
99+
100+
to run a single test:
101+
102+
```bash
103+
$> swift test --filter PackageGraphTests.DependencyResolverTests/testBasics
104+
```
105+
106+
Or another example, to run tests for the test targets BuildTests and WorkspaceTests, but skip some test cases:
107+
108+
```bash
109+
$> swift test --filter BuildTests --skip BuildPlanTests --filter WorkspaceTests --skip InitTests
110+
```
111+
112+
To run the performance tests, enable them with an ENV variable:
113+
114+
```bash
115+
$> export TSC_ENABLE_PERF_TESTS=1
116+
$> swift test -c release --filter PerformanceTests
117+
```
118+
119+
### Using the bootstrap script
120+
121+
The bootstrap script is designed for building SwiftPM on systems that do not have Xcode or a toolchain installed.
122+
It is used on bare systems to bootstrap the Swift toolchain (including SwiftPM), and as such not typically used outside the Swift team.
123+
124+
the bootstrap script requires having [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/) installed.
125+
Please refer to the [Swift project repo](https://github.com/apple/swift/blob/master/README.md#macos) for installation instructions.
126+
127+
1. Clone [llbuild](https://github.com/apple/swift-llbuild) beside the SwiftPM directory.
128+
129+
```bash
130+
$> git clone https://github.com/apple/swift-llbuild llbuild
131+
```
132+
133+
Note: Make sure the directory for llbuild is called "llbuild" and not
134+
"swift-llbuild".
135+
136+
2. Clone [Yams](https://github.com/jpsim/yams) beside the SwiftPM directory.
137+
138+
```bash
139+
$> git clone https://github.com/jpsim/yams
140+
```
141+
142+
3. Clone [swift-driver](https://github.com/apple/swift-driver) beside the SwiftPM directory.
143+
144+
```bash
145+
$> git clone https://github.com/apple/swift-driver
146+
```
147+
148+
4. Clone [swift-argument-parser](https://github.com/apple/swift-argument-parser) beside the SwiftPM directory and check out tag with the [latest version](https://github.com/apple/swift-argument-parser/tags).
149+
150+
For example, if the latest tag is 0.3.1:
151+
```bash
152+
$> git clone https://github.com/apple/swift-argument-parser --branch 0.3.1
153+
```
154+
155+
#### Building
156+
157+
```bash
158+
$> Utilities/bootstrap build
159+
```
160+
161+
See "Using the Command Line / Building" section above for more information on how to test the new artifacts.
162+
163+
#### Testing
164+
165+
```bash
166+
$> Utilities/bootstrap test
167+
```
168+
169+
## Testing locally
170+
171+
Before submitting code modification as Pull Requests, test locally across the supported platforms and build variants.
172+
173+
1. If using Xcode, run all the unit tests and verify they pass.
174+
2. If using the Command Line, run all the unit tests and verify they pass.
175+
176+
```bash
177+
$> swift test
178+
```
179+
180+
3. Optionally: Test with the bootstrap script as well.
181+
182+
```bash
183+
$> Utilities/bootstrap test
184+
```
185+
186+
When developing on macOS and need to test on Linux, install [Docker](https://www.docker.com/products/docker-desktop) and use the following commands:
187+
188+
```bash
189+
$> Utilities/Docker/docker-utils build # will build an image with the latest Swift snapshot
190+
$> Utilities/Docker/docker-utils bootstrap # will bootstrap SwiftPM on the Linux container
191+
$> Utilities/Docker/docker-utils run bash # to run an interactive Bash shell in the container
192+
$> Utilities/Docker/docker-utils swift-build # to run swift-build in the container
193+
$> Utilities/Docker/docker-utils swift-test # to run swift-test in the container
194+
$> Utilities/Docker/docker-utils swift-run # to run swift-run in the container
195+
```
196+
197+
## Creating Pull Requests
198+
1. Fork: https://github.com/apple/swift-package-manager
199+
2. Clone a working copy of your fork
200+
3. Create a new branch
201+
4. Make your code changes
202+
5. Try to keep your changes (when possible) below 200 lines of code.
203+
6. We use [SwiftFormat](https://www.github.com/nicklockwood/SwiftFormat) to enforce code style. Please install and run SwiftFormat before submitting your PR.
204+
7. Commit (include the Radar link or JIRA issue id in the commit message if possible and a description your changes). Try to have only 1 commit in your PR (but, of course, if you add changes that can be helpful to be kept aside from the previous commit, make a new commit for them).
205+
8. Push the commit / branch to your fork
206+
9. Make a PR from your fork / branch to `apple: main`
207+
10. While creating your PR, make sure to follow the PR Template providing information about the motivation and highlighting the changes.
208+
11. Reviewers are going to be automatically added to your PR
209+
12. Merge pull request when you received approval from the reviewers (one or more)
210+
211+
## Using Continuous Integration
212+
SwiftPM uses [swift-ci](https://ci.swift.org) infrastructure for its continuous integration testing. The bots can be triggered on pull-requests if you have commit access. Otherwise, ask one of the code owners to trigger them for you.
213+
214+
Run tests with the trunk compiler and other projects. This is **required** before
215+
a pull-request can be merged.
216+
217+
```
218+
@swift-ci please smoke test
219+
```
220+
221+
Run just the self-hosted tests. This has fast turnaround times so it can be used
222+
to get quick feedback.
223+
224+
Note: Smoke tests are still required for merging pull-requests.
225+
226+
## Advanced
227+
### Using Custom Swift Compilers
228+
SwiftPM needs the Swift compiler to parse `Package.swift` manifest files and to
229+
compile Swift source files. You can use the `SWIFT_EXEC` and `SWIFT_EXEC_MANIFEST`
230+
environment variables to control which compiler to use for these operations.
231+
232+
`SWIFT_EXEC_MANIFEST`: This variable controls which compiler to use for parsing
233+
`Package.swift` manifest files. The lookup order for the manifest compiler is:
234+
`SWIFT_EXEC_MANIFEST`, `swiftc` adjacent to the `swiftpm` binaries, then `SWIFT_EXEC`
235+
236+
`SWIFT_EXEC`: This variable controls which compiler to use for compiling Swift
237+
sources. The lookup order for the sources' compiler is: `SWIFT_EXEC`, then `swiftc` adjacent
238+
to `swiftpm` binaries. This is also useful for Swift compiler developers when they
239+
want to use a debug compiler with SwiftPM.
240+
241+
```bash
242+
$> SWIFT_EXEC=/path/to/my/built/swiftc swift build
243+
```
244+
245+
### Overriding the Path to the Runtime Libraries
246+
SwiftPM computes the path of its runtime libraries relative to where it is
247+
installed. This path can be overridden by setting the environment variable
248+
`SWIFTPM_PD_LIBS` to a directory containing the libraries, or a colon-separated list of
249+
absolute search paths. SwiftPM will choose the first
250+
path which exists on disk. If none of the paths are present on disk, it will fall
251+
back to built-in computation.
252+
253+
### Making changes in TSC targets
254+
SwiftPM uses [Tools Support Core](https://github.com/apple/swift-tools-support-core) (aka TSC) for many of its general purpose utilities. Changes in SwiftPM often require changes in TSC first. To coordinate changes, open a PR against TSC first, then a second one against SwiftPM pulling the correct TSC version.
255+
256+
## Community and Support
257+
If you want to connect with the Swift community you can:
258+
* Use Swift Forums: [https://forums.swift.org/c/development/SwiftPM](https://forums.swift.org/c/development/SwiftPM)
259+
* Contact the CODEOWNERS: https://github.com/apple/swift-package-manager/blob/main/CODEOWNERS
260+
261+
## Additional resources
262+
* `Swift.org` Contributing page
263+
[https://swift.org/contributing/](https://swift.org/contributing/)
264+
* License
265+
[https://swift.org/LICENSE.txt](https://swift.org/LICENSE.txt)
266+
* Code of Conduct
267+
[https://swift.org/community/#code-of-conduct](https://swift.org/community/#code-of-conduct)
268+
269+
## Troubleshooting
270+
* If during `swift build` you encounter this error:
271+
```bash
272+
/../apple-repos/swift-package-manager/.build/checkouts/swift-driver/Sources/SwiftDriver/Explicit Module Builds/InterModuleDependencyGraph.swift:102:3: error: unknown attribute '_spi'
273+
@_spi(Testing) public var isFramework: Bool
274+
^
275+
```
276+
Make sure you are using SwiftPM 5.3
277+
```bash
278+
$> swift package --version
279+
Swift Package Manager - Swift 5.3.0
280+
```
281+
* If during `swift build` you encounter this error:
282+
```bash
283+
/../swift-package-manager/Sources/PackageLoading/Target+PkgConfig.swift:84:36: error: type 'PkgConfigError' has no member 'prohibitedFlags'
284+
error = PkgConfigError.prohibitedFlags(filtered.unallowed.joined(separator: ", "))
285+
~~~~~~~~~~~~~~ ^~~~~~~~~~~~~~~
286+
```
287+
Make sure to update your TSC (Tools Support Core):
288+
```bash
289+
$> swift package update
290+
```
291+
Alternatively, if you are using Xcode, you can update to the latest version of all packages:
292+
**Xcode App** > *File* > *Swift Packages* > *Update to Latest Package Versions*

0 commit comments

Comments
 (0)