Skip to content

Commit fdb6662

Browse files
tomerdtomerd
authored
refactor contribution docs (#3578)
motivation: follow more conventional documentation setup changes: * move the content from Documentation/Contributing.md to CONTRIBUTING.md * Delete Contributing.md * Update README.md
1 parent 5e4695d commit fdb6662

File tree

3 files changed

+384
-425
lines changed

3 files changed

+384
-425
lines changed

‎CONTRIBUTING.md

Lines changed: 369 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,377 @@
1+
# Contributing to Swift Package Manager
2+
3+
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.
4+
5+
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).
6+
7+
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).
8+
9+
For more information about making contributions to the Swift project in general see [Swift Contribution Guide](https://swift.org/contributing/).
10+
11+
## Reporting issues
12+
13+
Issues are tracked using [SwiftPM JIRA Bug Tracker](https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22).
14+
15+
Please follow the [guide for filing quality bug reports](https://github.com/apple/swift-package-manager/blob/main/Documentation/Resources.md#reporting-a-good-swiftpm-bug).
16+
17+
## Setting up the development environment
18+
19+
First, clone a copy of SwiftPM code from https://github.com/apple/swift-package-manager.
20+
21+
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.
22+
23+
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:
24+
25+
### Using Xcode (Easiest)
26+
27+
1. Install Xcode from [https://developer.apple.com/xcode](https://developer.apple.com/xcode) (including betas!).
28+
2. Verify the expected version of Xcode was installed.
29+
3. Open SwiftPM's `Package.swift` manifest with Xcode, and use Xcode to edit the code, build, and run the tests.
30+
31+
### Using the Command Line
32+
33+
If you are using macOS and have Xcode installed, you can use Swift from the command line immediately.
34+
35+
If you are not using macOS or do not have Xcode installed, you need to download and install a toolchain.
36+
37+
#### Installing a toolchain
38+
39+
1. Download a toolchain from https://swift.org/download/
40+
2. Install it and verify the expected version of the toolchain was installed:
41+
42+
**macOS**
43+
44+
```bash
45+
$> export TOOLCHAINS=swift
46+
$> xcrun --find swift
47+
/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/swift
48+
$> swift package --version
49+
Swift Package Manager - Swift 5.3.0
50+
$> swift --version
51+
Apple Swift version 5.3
52+
```
53+
54+
**Linux**
55+
56+
```bash
57+
$> export PATH=/path/to/swift-toolchain/usr/bin:"${PATH}"
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+
## Local Development
69+
70+
With a Swift toolchain installed and the SwiftPM code cloned, you are ready to make changes and test them locally.
71+
72+
### Building
73+
74+
```bash
75+
$> swift build
76+
```
77+
78+
A successful build will create a `.build/` directory with the following approximate structure:
79+
80+
```
81+
artifacts
82+
checkouts
83+
debug
84+
repositories
85+
x86_64-apple-macosx
86+
```
87+
88+
Binary artifacts are located in `x86_64-apple-macosx/` when building on macOS,
89+
or the equivalent on other architectures and operating systems.
90+
91+
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/`:
92+
93+
```bash
94+
$> cd /tmp && mkdir hello && cd hello
95+
$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-package init
96+
$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-build
97+
```
98+
99+
### Testing
100+
101+
```bash
102+
$> swift test
103+
```
104+
105+
to run a single test:
106+
107+
```bash
108+
$> swift test --filter PackageGraphTests.DependencyResolverTests/testBasics
109+
```
110+
111+
Or another example, to run tests for the test targets BuildTests and WorkspaceTests, but skip some test cases:
112+
113+
```bash
114+
$> swift test --filter BuildTests --skip BuildPlanTests --filter WorkspaceTests --skip InitTests
115+
```
116+
117+
To run the performance tests, enable them with an ENV variable:
118+
119+
```bash
120+
$> export TSC_ENABLE_PERF_TESTS=1
121+
$> swift test -c release --filter PerformanceTests
122+
```
123+
124+
### The bootstrap script
125+
126+
The bootstrap script is designed for building SwiftPM on systems that do not have Xcode or a toolchain installed.
127+
It is used on bare systems to bootstrap the Swift toolchain (including SwiftPM), and as such not typically used outside the Swift team.
128+
129+
The bootstrap script requires having [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/) installed.
130+
Please refer to the [_Get Started_ guide](https://github.com/apple/swift/blob/main/docs/HowToGuides/GettingStarted.md#installing-dependencies) on the Swift project repository for installation instructions.
131+
132+
1. Clone [llbuild](https://github.com/apple/swift-llbuild) beside the SwiftPM directory.
133+
134+
```bash
135+
$> git clone https://github.com/apple/swift-llbuild llbuild
136+
```
137+
138+
Note: Make sure the directory for llbuild is called "llbuild" and not
139+
"swift-llbuild".
140+
141+
2. Clone [Yams](https://github.com/jpsim/yams) beside the SwiftPM directory.
142+
143+
```bash
144+
$> git clone https://github.com/jpsim/yams
145+
```
146+
147+
3. Clone [swift-driver](https://github.com/apple/swift-driver) beside the SwiftPM directory.
148+
149+
```bash
150+
$> git clone https://github.com/apple/swift-driver
151+
```
152+
153+
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).
154+
155+
For example, if the latest tag is 0.3.1:
156+
```bash
157+
$> git clone https://github.com/apple/swift-argument-parser --branch 0.3.1
158+
```
159+
160+
5. Clone [swift-crypto](https://github.com/apple/swift-crypto) beside the SwiftPM directory and check out tag with the [latest version](https://github.com/apple/swift-crypto/tags).
161+
162+
For example, if the latest tag is 1.1.3:
163+
```bash
164+
$> git clone https://github.com/apple/swift-crypto --branch 1.1.3
165+
```
166+
167+
#### Building
168+
169+
```bash
170+
$> Utilities/bootstrap build
171+
```
172+
173+
See "Using the Command Line / Building" section above for more information on how to test the new artifacts.
174+
175+
#### Testing
176+
177+
```bash
178+
$> Utilities/bootstrap test
179+
```
180+
181+
## Working with Docker to build and test for Linux
182+
183+
When developing on macOS and need to test on Linux, install
184+
[Docker](https://www.docker.com/products/docker-desktop) and
185+
[Docker compose](https://docs.docker.com/compose/install/) and
186+
use the following docker compose commands:
187+
188+
Prepare the underlying image with the selected Ubuntu and Swift versions:
189+
190+
```bash
191+
docker-compose \
192+
-f Utilities/docker/docker-compose.yaml \
193+
-f Utilities/docker/docker-compose.<os-version>.<swift-version>.yaml \
194+
build
195+
```
196+
197+
Start an interactive shell session:
198+
199+
```bash
200+
docker-compose \
201+
-f Utilities/docker/docker-compose.yaml \
202+
-f Utilities/docker/docker-compose.<os-version>.<swift-version>.yaml \
203+
run --rm shell
204+
```
205+
206+
Build SwiftPM (using the pre-installed SwiftPM version).
207+
208+
```bash
209+
docker-compose \
210+
-f Utilities/docker/docker-compose.yaml \
211+
-f Utilities/docker/docker-compose.<os-version>.<swift-version>.yaml \
212+
run --rm build
213+
```
214+
215+
Test SwiftPM (using the pre-installed SwiftPM version).
216+
217+
```bash
218+
docker-compose \
219+
-f Utilities/docker/docker-compose.yaml \
220+
-f Utilities/docker/docker-compose.<os-version>.<swift-version>.yaml \
221+
run --rm test
222+
```
223+
224+
Build SwiftPM using the bootstrap script:
225+
226+
```bash
227+
docker-compose \
228+
-f Utilities/docker/docker-compose.yaml \
229+
-f Utilities/docker/docker-compose.<os-version>.<swift-version>.yaml \
230+
run --rm bootstrap-build
231+
```
232+
233+
Test SwiftPM using the bootstrap script:
234+
235+
```bash
236+
docker-compose \
237+
-f Utilities/docker/docker-compose.yaml \
238+
-f Utilities/docker/docker-compose.<os-version>.<swift-version>.yaml \
239+
run --rm bootstrap-test
240+
```
241+
242+
Note there are several Linux and Swift versions options to choose from, e.g.:
243+
244+
`docker-compose.1804.53.yaml` => Ubuntu 18.04, Swift 5.3
245+
246+
`docker-compose.2004.54.yaml` => Ubuntu 20.04, Swift 5.4
247+
248+
`docker-compose.2004.main.yaml` => Ubuntu 20.04, Swift nightly
249+
250+
## Creating Pull Requests
251+
252+
1. Fork: https://github.com/apple/swift-package-manager
253+
2. Clone a working copy of your fork
254+
3. Create a new branch
255+
4. Make your code changes
256+
5. Try to keep your changes (when possible) below 200 lines of code.
257+
6. We use [SwiftFormat](https://www.github.com/nicklockwood/SwiftFormat) to enforce code style. Please install and run SwiftFormat before submitting your PR.
258+
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).
259+
8. Push the commit / branch to your fork
260+
9. Make a PR from your fork / branch to `apple: main`
261+
10. While creating your PR, make sure to follow the PR Template providing information about the motivation and highlighting the changes.
262+
11. Reviewers are going to be automatically added to your PR
263+
12. Merge pull request when you received approval from the reviewers (one or more)
264+
1265
By submitting a pull request, you represent that you have the right to license
2266
your contribution to Apple and the community, and agree by submitting the patch
3267
that your contributions are licensed under the [Swift
4268
license](https://swift.org/LICENSE.txt).
5269

6-
---
270+
## Continuous Integration
271+
272+
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.
273+
274+
To run smoke test suite with the trunk compiler and other projects use:
275+
276+
```
277+
@swift-ci please smoke test
278+
```
279+
280+
This is **required** before a pull-request can be merged.
281+
282+
283+
To run just the self-hosted test suite (faster turnaround times so it can be used to get quick feedback) use:
284+
285+
```
286+
@swift-ci please smoke test self hosted
287+
```
288+
289+
290+
To run the swift toolchain test suite including SwiftPM use:
291+
292+
```
293+
@swift-ci please test
294+
```
295+
296+
297+
To run package compatibility test suite (validates we do not break 3rd party packages) use:
298+
299+
```
300+
@swift-ci please test package compatibility
301+
```
302+
303+
## Advanced
304+
305+
### Using Custom Swift Compilers
306+
307+
SwiftPM needs the Swift compiler to parse `Package.swift` manifest files and to
308+
compile Swift source files. You can use the `SWIFT_EXEC` and `SWIFT_EXEC_MANIFEST`
309+
environment variables to control which compiler to use for these operations.
310+
311+
`SWIFT_EXEC_MANIFEST`: This variable controls which compiler to use for parsing
312+
`Package.swift` manifest files. The lookup order for the manifest compiler is:
313+
`SWIFT_EXEC_MANIFEST`, `swiftc` adjacent to the `swiftpm` binaries, then `SWIFT_EXEC`
314+
315+
`SWIFT_EXEC`: This variable controls which compiler to use for compiling Swift
316+
sources. The lookup order for the sources' compiler is: `SWIFT_EXEC`, then `swiftc` adjacent
317+
to `swiftpm` binaries. This is also useful for Swift compiler developers when they
318+
want to use a debug compiler with SwiftPM.
319+
320+
```bash
321+
$> SWIFT_EXEC=/path/to/my/built/swiftc swift build
322+
```
323+
324+
### Overriding the Path to the Runtime Libraries
325+
326+
SwiftPM computes the path of its runtime libraries relative to where it is
327+
installed. This path can be overridden by setting the environment variable
328+
`SWIFTPM_PD_LIBS` to a directory containing the libraries, or a colon-separated list of
329+
absolute search paths. SwiftPM will choose the first
330+
path which exists on disk. If none of the paths are present on disk, it will fall
331+
back to built-in computation.
332+
333+
### Making changes in TSC targets
334+
335+
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.
336+
337+
## Community and Support
338+
339+
If you want to connect with the Swift community you can:
340+
* Use Swift Forums: [https://forums.swift.org/c/development/SwiftPM](https://forums.swift.org/c/development/SwiftPM)
341+
* Contact the CODEOWNERS: https://github.com/apple/swift-package-manager/blob/main/CODEOWNERS
342+
343+
## Additional resources
344+
345+
* `Swift.org` Contributing page
346+
[https://swift.org/contributing/](https://swift.org/contributing/)
347+
* License
348+
[https://swift.org/LICENSE.txt](https://swift.org/LICENSE.txt)
349+
* Code of Conduct
350+
[https://swift.org/community/#code-of-conduct](https://swift.org/community/#code-of-conduct)
7351

8-
Before submitting the pull request, please make sure you have tested your
9-
changes and that they follow the SwiftPM project [guidelines for contributing
10-
code](Documentation/Contributing.md).
352+
## Troubleshooting
11353

12-
---
354+
* If during `swift build` you encounter this error:
355+
```bash
356+
/../apple-repos/swift-package-manager/.build/checkouts/swift-driver/Sources/SwiftDriver/Explicit Module Builds/InterModuleDependencyGraph.swift:102:3: error: unknown attribute '_spi'
357+
@_spi(Testing) public var isFramework: Bool
358+
^
359+
```
360+
Make sure you are using SwiftPM 5.3
361+
```bash
362+
$> swift package --version
363+
Swift Package Manager - Swift 5.3.0
364+
```
365+
* If during `swift build` you encounter this error:
366+
```bash
367+
/../swift-package-manager/Sources/PackageLoading/Target+PkgConfig.swift:84:36: error: type 'PkgConfigError' has no member 'prohibitedFlags'
368+
error = PkgConfigError.prohibitedFlags(filtered.unallowed.joined(separator: ", "))
369+
~~~~~~~~~~~~~~ ^~~~~~~~~~~~~~~
370+
```
371+
Make sure to update your TSC (Tools Support Core):
372+
```bash
373+
$> swift package update
374+
```
375+
Alternatively, if you are using Xcode, you can update to the latest version of all packages:
376+
**Xcode App** > *File* > *Swift Packages* > *Update to Latest Package Versions*
13377

14-
Issues are tracked using https://bugs.swift.org/

0 commit comments

Comments
 (0)