|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Contributions to Foundation are welcome! This project follows the [contribution guidelines for the Swift project](https://swift.org/contributing/#reporting-bugs). A few additional details are outlined below. |
| 4 | + |
| 5 | +## Bug Reports |
| 6 | + |
| 7 | +You can use the `Foundation` component in the [bug reporter](https://bugs.swift.org) if you know your bug is specifically about Swift Foundation. |
| 8 | + |
| 9 | +Please remember to include platform information with your report. If the bug is about the Foundation framework on Darwin, then please use the [Apple bug reporting system](https://bugreport.apple.com). |
| 10 | + |
| 11 | +## Pull Requests |
| 12 | + |
| 13 | +Before embarking on a large amount of work to implement missing functionality, please double-check with the community on the [swift-corelibs-dev](https://lists.swift.org/mailman/listinfo/swift-corelibs-dev) mailing list. Someone may already be working in this area, and we want to avoid duplication of work. |
| 14 | + |
| 15 | +If your request includes functionality changes, please be sure to test your code on Linux as well as OS X. Differences in the compiler and runtime on each platform means that code that compiles and runs correctly on Darwin (where the Objective-C runtime is present) may not compile at all on Linux. |
| 16 | + |
| 17 | +##### Review |
| 18 | + |
| 19 | +Each pull request will be reviewed by a code owner before merging. |
| 20 | + |
| 21 | +* Pull requests should contain small, incremental change. |
| 22 | +* Focus on one task. If a pull request contains several unrelated commits, we will ask for the pull request to be split up. |
| 23 | +* Please squash work-in-progress commits. Each commit should stand on its own (including the addition of tests if possible). This allows us to bisect issues more effectively. |
| 24 | +* After addressing review feedback, please rebase your commit so that we create a clean history in the `master` branch. |
| 25 | + |
| 26 | +##### Tests |
| 27 | + |
| 28 | +All pull requests which contain code changes should come with a new set of automated tests, and every current test must pass on all supported platforms. |
| 29 | + |
| 30 | +##### Documentation |
| 31 | + |
| 32 | +Most of the methods in Foundation are lacking documentation. We appreciate your help in filling out documentation when you implement a method. Use the markdown syntax in the [Swift Naming Guidelines](https://swift.org/documentation/api-design-guidelines.html#write-doc-comment). |
| 33 | + |
| 34 | +## API Changes |
| 35 | + |
| 36 | +The interface of Foundation is intended to be both stable and cross-platform. This means that when API is added to Foundation, it is effectively permanent. |
| 37 | + |
| 38 | +It is therefore critical that any code change that affects the public-facing API go through a full `swift-evolution` review process. This gives us the chance to ensure several important requirements are satisfied: |
| 39 | + |
| 40 | +* The proposal aligns with our current goals for the upcoming release. |
| 41 | +* We are comfortable supporting the proposed API for the long term. |
| 42 | +* We believe we can make the same change to the API of Darwin Foundation. This could be done via changes in the overlay, changes in the compiler, or changes in Darwin Foundation itself. This must be addressed in every proposal. |
0 commit comments