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]_
+
+### SwiftMetrics 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,27 +3,29 @@ 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
+* [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)
+
 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).
 
 ## 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:
+SwiftPM is typically built with a pre-existing version of SwiftPM present on the system, but there are have 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. Open SwiftPM's `Package.swift manifest with Xcode.
 
 ### Using a Swift toolchain
 
 1. Download a toolchain from https://swift.org/download/
-
 2. Confirm the toolchain is installed correctly:
 
 *macOS*
@@ -71,7 +73,7 @@ $> ./swift/utils/build-script --preset=buildbot_swiftpm_macos_platform,tools=RA,
 $> ./swift/utils/build-script --preset=buildbot_swiftpm_linux_platform,tools=RA,stdlib=RA
 ```
 
-3. Clone [llbuild](https://github.com/apple/swift-llbuild) beside the package manager directory.
+1. Clone [llbuild](https://github.com/apple/swift-llbuild) beside the package manager directory.
 
 ```bash
 $> git clone https://github.com/apple/swift-llbuild llbuild
@@ -80,101 +82,38 @@ $> git clone https://github.com/apple/swift-llbuild llbuild
 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.
+2. Clone [Yams](https://github.com/jpsim/yams) beside the package manager directory.
 
 ```bash
 $> git clone https://github.com/jpsim/yams
 ```
 
-5. Clone [swift-driver](https://github.com/apple/swift-driver) beside the package manager directory.
+3. Clone [swift-driver](https://github.com/apple/swift-driver) beside the package manager directory.
 
 ```bash
 $> git clone https://github.com/apple/swift-driver
 ```
 
-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).
+4. 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).
 
 For example, if the latest tag is 0.3.1:
 ```bash
 $> git clone https://github.com/apple/swift-argument-parser --branch 0.3.1
 ```
 
-7. Build the Swift Package Manager.
+5. Build the Swift Package Manager.
 
 ```bash
 $> cd swiftpm
 $> Utilities/bootstrap build
 ```
 
- 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.
+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.
 
 This command builds the Package Manager inside the `.build/` directory.
     Run the bootstrap script to rebuild after making a change to the source
     code.
 
-<a id="self-hosting">*_Self Hosting_*</a>:  
-
-It is possible to build SwiftPM with itself using SwiftPM present in latest
-release of Xcode or the latest trunk snapshot on Linux.
-
-```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
-```
-
-Note: PackageDescription v4 is not available when developing using this method.
-
-This method can also used be used for performance testing. Use the following
-command run SwiftPM's performance tests:
-
-```bash
-$> export TSC_ENABLE_PERF_TESTS=1
-$> swift test -c release --filter PerformanceTests
-```
-
-<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
-
-```bash
-$> ./swift/utils/build-script --preset=buildbot_swiftpm_macos_platform,tools=RA,stdlib=RA
-```
-
-### Linux
-
-```bash
-$> ./swift/utils/build-script --preset=buildbot_swiftpm_linux_platform,tools=RA,stdlib=RA
-```
-
-Once the build is complete, you should be able to run the swiftpm binaries from the build folder.
-
-### Example
-
-```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
-```
-
-8. Test the Swift Package Manager.
-
-```bash
-$> Utilities/bootstrap test
-```
-
 ## Building
 1. Pull the SwiftPM repository:
 ```bash
@@ -257,22 +196,18 @@ $> 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
@@ -307,13 +242,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

Utilities/bootstrap

@@ -645,7 +645,7 @@ def get_llbuild_source_path(args):
     llbuild_path = os.path.join(args.project_root, "..", "llbuild")
     if os.path.exists(llbuild_path):
         return llbuild_path
-    note("clone llbuild next to swiftpm directory; see development docs: https://github.com/apple/swift-package-manager/blob/master/Documentation/Contributing.md#using-trunk-snapshot")
+    note("clone llbuild next to swiftpm directory; see development docs: https://github.com/apple/swift-package-manager/blob/master/Documentation/Contributing.md")
     error("unable to find llbuild source directory at %s" % llbuild_path)
 
 def get_swiftpm_env_cmd(args):