Repository: apple/swift-docc (swift)

Issue:
Update contributor documentation to reflect GitHub Issues migration
Now that we've migrated from bugs.swift.org to GitHub Issues, we should update the contributor documentation to reflect this.

Pull request:
Bug/issue #, if applicable: https://github.com/apple/swift-docc/issues/231

## Summary

Updates the README and CONTRIBUTING documents to reflect that Swift-DocC has migrated from bugs.swift.org to GitHub Issues.

Also adds issue templates for bug reports and feature requests.

## Notes

I think we should migrate to the new [GitHub Issues Forms syntax](https://github.blog/changelog/2021-06-23-issues-forms-beta-for-public-repositories/) in the near-future but thought it made sense to get _some_ templates up initially and learned about the new format a little too late. I've filed https://github.com/apple/swift-docc/issues/232 to track this as a future enhancement.

## Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

- [ ] ~~Added tests~~ NFC
- [x] Ran the `./bin/test` script and it succeeded
- [x] Updated documentation if necessary

Patch:
diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
new file mode 100644
index 0000000000..c180a02140
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
@@ -0,0 +1,41 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+labels: bug
+---
+
+<!--
+	Thank you for contributing to Swift-DocC!
+
+	Before you submit your issue, please replace each paragraph
+	below with the relevant details for your bug, and complete
+	the steps in the checklist by placing an 'x' in each box:
+	
+	- [x] I've completed this task
+	- [ ] This task isn't completed
+-->
+
+Replace this paragraph with a short description of the incorrect behavior. 
+If you think this issue has been recently introduced and did not occur in an 
+earlier version, please note that. If possible, include the last version that 
+the behavior was correct in addition to your current version.
+
+### Checklist
+- [ ] If possible, I've reproduced the issue using the `main` branch of this package.
+- [ ] This issue hasn't been addressed in an [existing GitHub issue](https://github.com/apple/swift-docc/issues).
+
+### Expected behavior
+Describe what you expected to happen.
+
+### Actual behavior
+Describe or copy/paste the behavior you observe.
+
+### Steps to Reproduce
+Replace this paragraph with an explanation of how to reproduce the incorrect behavior. 
+This could include a reduced version of your documentation bundle,
+or a link to the documentation (or code) that is exhibiting the issue.
+
+### Swift-DocC Version Information
+
+**Swift-DocC version:** `5.6.0` for example, or a commit hash.
+**Swift Compiler version:** Output from `swiftc --version`.
diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md
new file mode 100644
index 0000000000..8db39e890f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md
@@ -0,0 +1,36 @@
+---
+name: Feature Request
+about: A suggestion for a new feature
+labels: enhancement
+---
+
+<!--
+	Thank you for contributing to Swift-DocC!
+
+	Before you submit your issue, please replace each paragraph
+	below with information about your proposed feature.
+-->
+
+### Feature Request: _<Feature Name>_
+
+#### Description:
+
+Replace this paragraph with a description of your proposed feature. 
+Sample documentation catalogs that show what's missing, 
+or what new capabilities will be possible, are very helpful! 
+Provide links to existing issues or external references/discussions, if appropriate.
+
+#### Motivation:
+
+Replace this paragraph with a description of the use-case this proposal is trying to serve.
+
+#### Importance:
+
+Replace this paragraph with a description of the importance of this change.
+Does this feature unlock entirely new use-cases? 
+Or is it possible to achieve the same functionality with existing functionality 
+and this change would improve the user experience?
+
+#### Alternatives Considered
+
+If you considered alternative approaches for this feature, please include them here.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000000..d130b8fbdd
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,24 @@
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2022 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See https://swift.org/LICENSE.txt for license information
+# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+# This is set to `false` to encourage users to use the provided templates instead
+# of beginning with a blank one.
+#
+# For details, see: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
+blank_issues_enabled: false
+
+contact_links:
+  - name: Discussion Forum
+    url: https://forums.swift.org/c/development/swift-docc
+    about: Ask and answer questions about Swift-DocC
+  - name: Swift-DocC Documentation
+    url: https://www.swift.org/documentation/docc/
+    about: Learn about how to use the Swift-DocC documentation tool in your projects
+  - name: Swift-DocC Technical Documentation
+    url: https://apple.github.io/swift-docc/documentation/swiftdocc/
+    about: Read Swift-DocC's technical API documentation
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0d9fb00b0f..f23549b4a7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,7 +35,9 @@ from the community.
 ### Contributing Code and Documentation
 
 Before contributing code or documentation to Swift-DocC,
-we encourage you to first create an issue on [Swift JIRA](https://bugs.swift.org/).
+we encourage you to first open a 
+[GitHub issue](https://github.com/apple/swift-docc/issues/new/choose) 
+for a bug report or feature request.
 This will allow us to provide feedback on the proposed change.
 However, this is not a requirement. If your contribution is small in scope,
 feel free to open a PR without first creating an issue.
@@ -141,8 +143,7 @@ requirements:
 When opening a pull request, please make sure to fill out the pull request template
 and complete all tasks mentioned there.
 
-Your PR should mention the number of the [Swift JIRA](https://bugs.swift.org/)
-issue your work is addressing (SR-NNNNN).
+Your PR should mention the number of the GitHub issue your work is addressing.
   
 Most PRs should be against the `main` branch. If your change is intended 
 for a specific release, you should also create a separate branch 
@@ -340,10 +341,10 @@ If you do not have commit access, please ask one of the code owners to trigger t
 ## Your First Contribution
 
 Unsure of where to begin contributing to Swift-DocC? You can start by looking at
-the bugs in the `Swift-DocC` component with the `StarterBug` label on
-[Swift JIRA](https://bugs.swift.org/issues/?jql=project%20%3D%20SR%20AND%20status%20in%20(Open%2C%20Reopened)%20AND%20component%20%3D%20Swift-DocC%20AND%20labels%20%3D%20StarterBug).
+the issues on the [good first issue](https://github.com/apple/swift-docc/contribute)
+page.
 
 Once you've found an issue to work on,
 follow the above instructions for [Building Swift-DocC](#building-swift-docc).
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
diff --git a/README.md b/README.md
index 8dd6ba8a2b..a8838b55b0 100644
--- a/README.md
+++ b/README.md
@@ -247,9 +247,10 @@ active development and source stability is not guaranteed.
 
 ### Submitting a Bug Report
 
-Swift-DocC tracks all bug reports with [Swift JIRA](https://bugs.swift.org/).
+Swift-DocC tracks all bug reports with 
+[GitHub Issues](https://github.com/apple/swift-docc/issues).
 When you submit a bug report we ask that you follow the
-Swift [Bug Reporting](https://swift.org/contributing/#reporting-bugs) guidelines
+[provided template](https://github.com/apple/swift-docc/issues/new?template=BUG_REPORT.md)
 and provide as many details as possible.
 
 > **Note:** You can use the [`environment`](bin/environment) script
@@ -266,8 +267,8 @@ that will help us track down the bug faster.
 
 ### Submitting a Feature Request
 
-For feature requests, please feel free to create an issue
-on [Swift JIRA](https://bugs.swift.org/) with the `New Feature` type
+For feature requests, please feel free to file a
+[GitHub issue](https://github.com/apple/swift-docc/issues/new?template=FEATURE_REQUEST.md)
 or start a discussion on the [Swift Forums](https://forums.swift.org/c/development/swift-docc).
 
 Don't hesitate to submit a feature request if you see a way
@@ -281,4 +282,4 @@ before being enabled by default.
 
 Please see the [contributing guide](/CONTRIBUTING.md) for more information.
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
diff --git a/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex+Ext.swift b/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex+Ext.swift
index 4296fcb418..4f19b3718b 100644
--- a/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex+Ext.swift
+++ b/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex+Ext.swift
@@ -80,7 +80,7 @@ extension RenderNode {
     func navigatorTitle() -> String? {
         let fragments: [DeclarationRenderSection.Token]?
         
-        // FIXME: Use `metadata.navigatorTitle` for all Swift symbols (SR-15947).
+        // FIXME: Use `metadata.navigatorTitle` for all Swift symbols (github.com/apple/swift-docc/issues/176).
         if identifier.sourceLanguage == .swift || (metadata.navigatorTitle ?? []).isEmpty {
             let pageType = navigatorPageType()
             guard ![.framework, .class, .structure, .enumeration, .protocol, .typeAlias, .associatedType].contains(pageType) else { return metadata.title }
diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift
index 6dc11c7a56..ed6a10672d 100644
--- a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift
+++ b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift
@@ -1311,7 +1311,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
                 // FIXME: Update with new SymbolKit API once available.
                 // This is a very inefficient way to gather the source languages
                 // represented in a symbol graph. Adding a dedicated SymbolKit API is tracked
-                // with SR-15551 and rdar://85982095.
+                // with github.com/apple/swift-docc-symbolkit/issues/32 and rdar://85982095.
                 let symbolGraphLanguages = Set(
                     unifiedSymbolGraph.symbols.flatMap(\.value.sourceLanguages)
                 )
diff --git a/Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolReference.swift b/Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolReference.swift
index 472878b96e..97d3c19809 100644
--- a/Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolReference.swift
+++ b/Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolReference.swift
@@ -180,7 +180,7 @@ extension UnifiedSymbolGraph.Symbol {
     var sourceLanguages: Set<SourceLanguage> {
         // FIXME: Replace with new SymbolKit API once available.
         // Adding a dedicated SymbolKit API for this purpose is tracked
-        // with SR-15551 and rdar://85982095.
+        // with github.com/apple/swift-docc-symbolkit/issues/32 and rdar://85982095.
         return Set(
             pathComponents.keys.compactMap { selector in
                 return SourceLanguage(knownLanguageIdentifier: selector.interfaceLanguage)
diff --git a/Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift b/Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift
index e05d4f751c..7f660b61d1 100644
--- a/Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift
+++ b/Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift
@@ -108,7 +108,7 @@ public class DocumentationContentRenderer {
     /// Returns the given amount of minutes as a string, for example: "1hr 10min".
     func formatEstimatedDuration(minutes: Int) -> String? {
         // TODO: Use DateComponentsFormatter once it's available on Linux (rdar://59787899) and 
-        // when Swift-DocC supports generating localized documentation (SR-15352), since
+        // when Swift-DocC supports generating localized documentation (github.com/apple/swift-docc/issues/218), since
         // DateComponentsFormatter formats content based on the user's locale.
 //        let dateFormatter = DateComponentsFormatter()
 //        if #available(OSX 10.12, *) {
diff --git a/Sources/SwiftDocC/Model/SourceLanguage.swift b/Sources/SwiftDocC/Model/SourceLanguage.swift
index 2b88a2f1b5..79580e421c 100644
--- a/Sources/SwiftDocC/Model/SourceLanguage.swift
+++ b/Sources/SwiftDocC/Model/SourceLanguage.swift
@@ -133,7 +133,7 @@ public struct SourceLanguage: Hashable, Codable {
         id: "occ",
         idAliases: [
             "objective-c",
-            "c", // FIXME: DocC should display C as its own language (SR-16050).
+            "c", // FIXME: DocC should display C as its own language (github.com/apple/swift-docc/issues/169).
         ],
         linkDisambiguationID: "c"
     )


Test patch:
diff --git a/Tests/SwiftDocCTests/DocumentationService/ConvertService/ConvertServiceTests.swift b/Tests/SwiftDocCTests/DocumentationService/ConvertService/ConvertServiceTests.swift
index a4dcca1cab..0354827c32 100644
--- a/Tests/SwiftDocCTests/DocumentationService/ConvertService/ConvertServiceTests.swift
+++ b/Tests/SwiftDocCTests/DocumentationService/ConvertService/ConvertServiceTests.swift
@@ -676,7 +676,7 @@ class ConvertServiceTests: XCTestCase {
         #if os(Linux)
         throw XCTSkip("""
         Skipped on Linux due to an issue in Foundation.Codable where dictionaries are sometimes getting encoded as \
-        arrays. (SR-15036)
+        arrays. (github.com/apple/swift/issues/57363)
         """)
         #else
         let (testBundleURL, _, _) = try testBundleAndContext(
@@ -804,7 +804,7 @@ class ConvertServiceTests: XCTestCase {
         #if os(Linux)
         throw XCTSkip("""
         Skipped on Linux due to an issue in Foundation.Codable where dictionaries are sometimes getting encoded as \
-        arrays. (SR-15036)
+        arrays. (github.com/apple/swift/issues/57363)
         """)
         #else
         let (testBundleURL, _, _) = try testBundleAndContext(
@@ -847,7 +847,7 @@ class ConvertServiceTests: XCTestCase {
         #if os(Linux)
         throw XCTSkip("""
         Skipped on Linux due to an issue in Foundation.Codable where dictionaries are sometimes getting encoded as \
-        arrays. (SR-15036)
+        arrays. (github.com/apple/swift/issues/57363)
         """)
         #else
         let (testBundleURL, _, _) = try testBundleAndContext(
diff --git a/Tests/SwiftDocCTests/DocumentationService/DocumentationServer+DefaultTests.swift b/Tests/SwiftDocCTests/DocumentationService/DocumentationServer+DefaultTests.swift
index f8a568353b..2d36d61202 100644
--- a/Tests/SwiftDocCTests/DocumentationService/DocumentationServer+DefaultTests.swift
+++ b/Tests/SwiftDocCTests/DocumentationService/DocumentationServer+DefaultTests.swift
@@ -87,7 +87,7 @@ class DocumentationServer_DefaultTests: XCTestCase {
         
         // Instead of using an `XCTestExpectation`, use a Boolean due to a bug in
         // swift-corelibs-xctest on Linux for expectations that get over-fulfilled
-        // https://bugs.swift.org/browse/SR-12575.
+        // https://github.com/apple/swift/issues/55020.
         var hasLinkResolverBeenCalled = false
         
         let peerServer = DocumentationServer()
diff --git a/Tests/SwiftDocCTests/Rendering/RoundTripCoding.swift b/Tests/SwiftDocCTests/Rendering/RoundTripCoding.swift
index 2edd96c1a6..a7bae34324 100644
--- a/Tests/SwiftDocCTests/Rendering/RoundTripCoding.swift
+++ b/Tests/SwiftDocCTests/Rendering/RoundTripCoding.swift
@@ -51,7 +51,7 @@ func assertJSONRepresentation<Value: Decodable & Equatable>(
     
     let encoding: String.Encoding
     #if os(Linux) || os(Android)
-    // Work around a JSON decoding issue on Linux (SR-15035).
+    // Work around a JSON decoding issue on Linux (github.com/apple/swift/issues/57362).
     encoding = .utf8
     #else
     encoding = json.fastestEncoding