Add ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md

Author: federicobucchi

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,20 @@
+### Expected behavior
+_[what you expected to happen]_
+
+### Actual behavior
+_[what actually happened]_
+
+### Steps to reproduce
+
+1. ...
+2. ...
+
+### If possible, minimal yet complete reproducer code (or URL to code)
+
+_[anything to help us reproducing the issue]_
+
+### Swift Package Manager version/commit hash
+
+_[the Swift Package Manager tag/commit hash]_
+
+### Swift & OS version (output of `swift --version && uname -a`)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+_[One line description of your change]_
+
+### Motivation:
+
+_[Explain here the context, and why you're making that change. What is the problem you're trying to solve.]_
+
+### Modifications:
+
+_[Describe the modifications you've done.]_
+
+### Result:
+
+_[After your change, what will change.]_

Documentation/Contributing.md

@@ -3,30 +3,38 @@ There are several types of contributions one can make. Bug fixes, documentation
 
 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).
 
-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 Proposal](Documentation/Internals/PackageManagerCommunityProposal.md).
+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).
 
 For more information about making contributions to the Swift project in general see [Swift Contribution Guide](https://swift.org/contributing/).
 
 ## Reporting issues
-Report a bug guide: https://github.com/apple/swift-package-manager/blob/main/Documentation/Resources.md#reporting-a-good-swiftpm-bug.  
-JIRA Bug Tracker (a place where you can open bugs, enhancements to start to contribute): [https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22](https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22).
+* [SwiftPM JIRA Bug Tracker](https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22).
+* [Guide for filing quality bug reports](https://github.com/apple/swift-package-manager/blob/main/Documentation/Resources.md#reporting-a-good-swiftpm-bug).
 
 ## Development environment
 
-SwiftPM is typically built with a pre-existing versions of SwiftPM present on the system. Which can be obtained by installing the latest release of Xcode or a toolchain from swift.org. But there are have multiple ways to setup your development environment:
+First, clone a copy of SwiftPM code from https://github.com/apple/swift-package-manager.
+
+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.
+
+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:
 
 ### Using Xcode (Easiest)
 
-1. Install latest Xcode from https://developer.apple.com/xcode
-2. Open SwiftPM's `Package.swift` manifest with the latest release (including betas) of Xcode.
+1. Install Xcode from [https://developer.apple.com/xcode](https://developer.apple.com/xcode) (including betas!).
+2. Verify the expected version of Xcode was installed.
+3. Open SwiftPM's `Package.swift` manifest with Xcode, and use Xcode to edit the code, build, and run the tests.
 
-### Using a Swift toolchain
+### Using the Command Line
 
-1. Download a toolchain from https://swift.org/download/
+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.
 
-2. Confirm the toolchain is installed correctly:
+#### Installing the toolchain
 
-*macOS*
+1. Download a toolchain from https://swift.org/download/
+2. Install it and verify the expected version of the toolchain was installed:
+
+**macOS**
 ```bash
 $> export TOOLCHAINS=swift
 ```
@@ -41,7 +49,7 @@ $> swift --version
 Apple Swift version 5.3
 ```
 
-*Linux*
+**Linux**
 ```bash
 $> export PATH=/path/to/swift-toolchain/usr/bin:"${PATH}"
 ```
@@ -55,188 +63,127 @@ $> swift --version
 Apple Swift version 5.3
 ```
 
-3. Alternatively use tools like swiftenv that help manage toolchains versions.
-
-### Using the Swift Compiler Build Script
+Note:  Alternatively use tools like [swiftenv](https://github.com/kylef/swiftenv) that help manage toolchains versions.
 
-Follow these instructions to get the Swift sources and then execute the build-script using swiftpm preset:
+#### Building
 
-*macOS*
 ```bash
-$> ./swift/utils/build-script --preset=buildbot_swiftpm_macos_platform,tools=RA,stdlib=RA
+$> swift build
 ```
 
-*Linux*
+A successful build will create a `.build/` directory with the following approximate structure:
 ```bash
-$> ./swift/utils/build-script --preset=buildbot_swiftpm_linux_platform,tools=RA,stdlib=RA
+artifacts/
+checkouts/
+debug/
+repositories
+x86_64-apple-macosx
 ```
 
-3. Clone [llbuild](https://github.com/apple/swift-llbuild) beside the package manager directory.
+Binary artifacts are located in `x86_64-apple-macosx/` when building on macOS, 
+or the equivalent on other architectures and operating systems.
+
+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/`:
 
 ```bash
-$> git clone https://github.com/apple/swift-llbuild llbuild
+$> cd /tmp && mkdir hello && cd hello
+$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-package init
+$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-build
 ```
 
-Note: Make sure the directory for llbuild is called "llbuild" and not
-    "swift-llbuild".
-
-4. Clone [Yams](https://github.com/jpsim/yams) beside the package manager directory.
+#### Testing
 
 ```bash
-$> git clone https://github.com/jpsim/yams
+$> swift test
 ```
 
-5. Clone [swift-driver](https://github.com/apple/swift-driver) beside the package manager directory.
+to run a single test:
 
 ```bash
-$> git clone https://github.com/apple/swift-driver
+$> swift test --filter PackageGraphTests.DependencyResolverTests/testBasics
 ```
 
-6. Clone [swift-argument-parser](https://github.com/apple/swift-argument-parser) beside the package manager directory and check out tag with the [latest version](https://github.com/apple/swift-argument-parser/tags).
+Or another example, to run tests for the test targets BuildTests and WorkspaceTests, but skip some test cases:
 
-For example, if the latest tag is 0.3.1:
 ```bash
-$> git clone https://github.com/apple/swift-argument-parser --branch 0.3.1
+$> swift test --filter BuildTests --skip BuildPlanTests --filter WorkspaceTests --skip InitTests
 ```
 
-7. Build the Swift Package Manager.
+To run the performance tests, enable them with an ENV variable:
 
 ```bash
-$> cd swiftpm
-$> Utilities/bootstrap build
+$> export TSC_ENABLE_PERF_TESTS=1
+$> swift test -c release --filter PerformanceTests
 ```
 
- Note: The bootstrap script requires having [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/) installed. Please refer to the [Swift project repo](https://github.com/apple/swift/blob/master/README.md#macos) for installation instructions.
+### Using the bootstrap script
 
-This command builds the Package Manager inside the `.build/` directory.
-    Run the bootstrap script to rebuild after making a change to the source
-    code.
+The bootstrap script is designed for building SwiftPM on systems that do not have Xcode or a toolchain installed.
+It is used on bare systems to bootstrap the Swift toolchain (including SwiftPM), and as such not typically used outside the Swift team.
 
-<a id="self-hosting">*_Self Hosting_*</a>:  
+the bootstrap script requires having [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/) installed. 
+Please refer to the [Swift project repo](https://github.com/apple/swift/blob/master/README.md#macos) for installation instructions.
 
-It is possible to build SwiftPM with itself using SwiftPM present in latest
-release of Xcode or the latest trunk snapshot on Linux.
+1. Clone [llbuild](https://github.com/apple/swift-llbuild) beside the SwiftPM directory.
 
 ```bash
-# Build:
-$> swift build
-
-# Run all tests.
-$> swift test --parallel
-
-# Run a single test.
-For example, to only run the `PackageGraphTests.DependencyResolverTests/testBasics`
-$> swift test --filter PackageGraphTests.DependencyResolverTests/testBasics
-
-# Run tests for the test targets BuildTests and WorkspaceTests, but skip some test cases.
-$> swift test --filter BuildTests --skip BuildPlanTests --filter WorkspaceTests --skip InitTests
+$> git clone https://github.com/apple/swift-llbuild llbuild
 ```
 
-Note: PackageDescription v4 is not available when developing using this method.
+Note: Make sure the directory for llbuild is called "llbuild" and not
+    "swift-llbuild".
 
-This method can also used be used for performance testing. Use the following
-command run SwiftPM's performance tests:
+2. Clone [Yams](https://github.com/jpsim/yams) beside the SwiftPM directory.
 
 ```bash
-$> export TSC_ENABLE_PERF_TESTS=1
-$> swift test -c release --filter PerformanceTests
+$> git clone https://github.com/jpsim/yams
 ```
 
-<a id="swift-compiler-build-script">*E) _Using the Swift Compiler Build Script_*</a>:  
-
-Follow [these](https://github.com/apple/swift#getting-started) instructions to
-get the Swift sources and then execute the `build-script` using swiftpm preset:
-
-### macOS
+3. Clone [swift-driver](https://github.com/apple/swift-driver) beside the SwiftPM directory.
 
 ```bash
-$> ./swift/utils/build-script --preset=buildbot_swiftpm_macos_platform,tools=RA,stdlib=RA
+$> git clone https://github.com/apple/swift-driver
 ```
 
-### Linux
+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).
 
+For example, if the latest tag is 0.3.1:
 ```bash
-$> ./swift/utils/build-script --preset=buildbot_swiftpm_linux_platform,tools=RA,stdlib=RA
+$> git clone https://github.com/apple/swift-argument-parser --branch 0.3.1
 ```
 
-Once the build is complete, you should be able to run the swiftpm binaries from the build folder.
-
-### Example
+#### Building
 
 ```bash
-$> cd /tmp && mkdir hello && cd hello
-$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-package init
-$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-build
+$> Utilities/bootstrap build
 ```
 
-8. Test the Swift Package Manager.
+See "Using the Command Line / Building" section above for more information on how to test the new artifacts.
 
-```bash
-$> Utilities/bootstrap test
-```
+#### Testing
 
-## Building
-1. Pull the SwiftPM repository:
-```bash
-$> git clone https://github.com/apple/swift-package-manager.git
-```
-2. Run your first build:
 ```bash
-$> cd swift-package-manager
-$> swift build
+$> Utilities/bootstrap test
 ```
-Make sure the build did not fail.  
 
-A `.build/` folder will be generated and it should have inside a similar structure (including build binaries):
-```bash
-artifacts/
-checkouts/
-debug/
-repositories
-x86_64-apple-macosx
-debug.yaml
-manifest.db
-workspace-state.json 
-```
-Binaries (in the example above) are in `x86_64-apple-macosx/`.  
-If you need to build the generated binaries, run `swift-build` in inside `.build/`:
-```bash
-./.build/x86_64-apple-macosx/debug/swift-build
-```
+## Testing locally
 
-## Running Tests
-### Run all tests.
-```bash
-$> swift test
-```
-### Run a single test.
-```bash
-$> swift test --filter PackageGraphTests.DependencyResolverTests/testBasics
-```
-Or another example, to run tests for the test targets BuildTests and WorkspaceTests, but skip some test cases.
-```bash
-$> swift test --filter BuildTests --skip BuildPlanTests --filter WorkspaceTests --skip InitTests
-```
-Note: PackageDescription v4 is not available when developing using this method.
+Before submitting code modification as Pull Requests, test locally across the supported platforms and build variants.
 
-This method can also used be used for performance testing. Use the following command run SwiftPM's performance tests:
+1. If using Xcode, run all the unit tests and verify they pass.
+2. If using the Command Line, run all the unit tests and verify they pass.
 
 ```bash
-$> export TSC_ENABLE_PERF_TESTS=1
-$> swift test -c release --filter PerformanceTests
+$> swift test
 ```
 
-To test SwiftPM functionality using the newly created binaries, you can invoke them from the `.build` directory. For example:
+3. Optionally: Test with the bootstrap script as well.
 
 ```bash
-$> cd /tmp && mkdir hello && cd hello
-$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-package init
-$> /path/to/swiftpm/.build/x86_64-apple-macosx/debug/swift-build
+$> Utilities/bootstrap test
 ```
 
-## Testing on Linux with Docker
-For contributors on macOS who need to test on Linux, install Docker and use the
-following commands:
+When developing on macOS and need to test on Linux, install [Docker](https://www.docker.com/products/docker-desktop) and use the following commands:
 
 ```bash
 $> Utilities/Docker/docker-utils build # will build an image with the latest Swift snapshot
@@ -257,30 +204,27 @@ $> Utilities/Docker/docker-utils swift-run # to run swift-run in the container
 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).
 8. Push the commit / branch to your fork
 9. Make a PR from your fork / branch to `apple: main`
-10. Reviewers are going to be automatically added to your PR
-11. Merge pull request when you received approval from the reviewers (one or more)
+10. While creating your PR, make sure to follow the PR Template providing information about the motivation and highlighting the changes.
+11. Reviewers are going to be automatically added to your PR
+12. Merge pull request when you received approval from the reviewers (one or more)
 
 ## Using Continuous Integration
-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. The following commands are supported:
-
-```
-@swift-ci please smoke test
-```
+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.
 
 Run tests with the trunk compiler and other projects. This is **required** before
 a pull-request can be merged.
 
 ```
-@swift-ci please smoke test self hosted
+@swift-ci please smoke test
 ```
 
 Run just the self-hosted tests. This has fast turnaround times so it can be used
 to get quick feedback.
 
 Note: Smoke tests are still required for merging pull-requests.
 
-## Using Custom Swift Compilers
+## Advanced
+### Using Custom Swift Compilers
 SwiftPM needs the Swift compiler to parse `Package.swift` manifest files and to
 compile Swift source files. You can use the `SWIFT_EXEC` and `SWIFT_EXEC_MANIFEST`
 environment variables to control which compiler to use for these operations.
@@ -298,7 +242,7 @@ want to use a debug compiler with SwiftPM.
 $> SWIFT_EXEC=/path/to/my/built/swiftc swift build
 ```
 
-## Overriding the Path to the Runtime Libraries
+### Overriding the Path to the Runtime Libraries
 SwiftPM computes the path of its runtime libraries relative to where it is
 installed. This path can be overridden by setting the environment variable
 `SWIFTPM_PD_LIBS` to a directory containing the libraries, or a colon-separated list of
@@ -307,13 +251,12 @@ path which exists on disk. If none of the paths are present on disk, it will fal
 back to built-in computation.
 
 ## Making changes in TSC targets
-All targets with the prefix TSC define the interface for the tools support core. Those APIs might be used in other projects as well and need to be updated in this repository by copying their sources directories to the TSC repository. The repository can be found [here](https://github.com/apple/swift-tools-support-core).
+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.
 
 ## Community and Support
 If you want to connect with the Swift community you can:
 * Use Swift Forums: [https://forums.swift.org/c/development/SwiftPM](https://forums.swift.org/c/development/SwiftPM)
 * Contact the CODEOWNERS: https://github.com/apple/swift-package-manager/blob/main/CODEOWNERS
-(mailing lists are usually the best place to go for help: [[email protected]](mailto:[email protected]), [[email protected]](mailto:[email protected]), [[email protected]](mailto:[email protected])
 
 ## Additional resources
 * `Swift.org` Contributing page