diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index a0c963f..3f60cac 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,14 +1,6 @@ -blank_issues_enabled: false +--- +blank_issues_enabled: true contact_links: - - name: "💬 Swift Documentation Forums" + - name: Swift Documentation Forums url: "https://forums.swift.org/c/development/swift-docc/80" - about: "Discuss documentation content, propose major additions, or ask questions about Swift documentation" - - name: "🛠️ Documentation Tooling Forums" - url: "https://forums.swift.org/c/92" - about: "Questions about using Swift-DocC, documentation build tools, or authoring documentation" - - name: "📚 Swift Documentation Website" - url: "https://www.swift.org/documentation/" - about: "View the published Swift documentation" - - name: "📖 Contributing Guide" - url: "https://github.com/swiftlang/docs/blob/main/CONTRIBUTING.md" - about: "Read about style guidelines, proposing content, and the contribution process" + about: "Discuss documentation content or propose major additions" diff --git a/.github/ISSUE_TEMPLATE/content-error.yml b/.github/ISSUE_TEMPLATE/content-error.yml deleted file mode 100644 index 030053f..0000000 --- a/.github/ISSUE_TEMPLATE/content-error.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: "Content Error" -description: "Report inaccurate or incorrect information in existing documentation" -labels: ["content error", "triage needed"] -body: - - type: markdown - attributes: - value: | - Thank you for helping improve the Swift documentation! - - Use this template to report inaccurate, misleading, or incorrect content. - If you're suggesting improvements without claiming inaccuracy, use the Enhancement template instead. - - - type: input - id: location - attributes: - label: "Location (URL)" - description: "The URL of the page with the error (from swift.org or local preview)" - placeholder: "https://www.swift.org/documentation/..." - validations: - required: true - - - type: textarea - id: description - attributes: - label: "Description" - description: "What's wrong with the current content?" - placeholder: "Be specific about what information is incorrect or inaccurate" - validations: - required: true - - - type: textarea - id: correction - attributes: - label: "Suggested Correction" - description: "What should the documentation say instead?" - placeholder: "Provide the corrected information or approach" - validations: - required: false - - - type: textarea - id: context - attributes: - label: "Additional Context" - description: "Any supporting information, references, or examples" - placeholder: "Links to Swift Evolution proposals, API documentation, or code examples" - validations: - required: false diff --git a/.github/ISSUE_TEMPLATE/content-issue.yml b/.github/ISSUE_TEMPLATE/content-issue.yml new file mode 100644 index 0000000..2303993 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/content-issue.yml @@ -0,0 +1,24 @@ +--- +name: "Content Issue" +description: >- + Report an error, suggest an improvement, + or flag a problem with existing documentation +labels: ["triage needed"] +body: + - type: input + id: location + attributes: + label: "Page URL" + description: >- + Link to the page with the issue + placeholder: "https://www.swift.org/documentation/..." + validations: + required: false + + - type: textarea + id: description + attributes: + label: "Description" + description: "What's wrong or what could be better?" + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/content-proposal.yml b/.github/ISSUE_TEMPLATE/content-proposal.yml index cd862b6..e1cbe47 100644 --- a/.github/ISSUE_TEMPLATE/content-proposal.yml +++ b/.github/ISSUE_TEMPLATE/content-proposal.yml @@ -1,56 +1,22 @@ +--- name: "Content Proposal" description: "Propose new documentation topics or articles" -labels: ["content proposal", "needs forum discussion"] +labels: ["content proposal"] body: - type: markdown attributes: value: | - Thank you for proposing new Swift documentation! + For significant new content, consider starting + a discussion on the + [Swift Forums][1] first. - For significant new content, please consider starting a discussion on the - [Swift Forums](https://forums.swift.org/c/development/swift-docc/80) first. - - See our [Contributing Guide](https://github.com/swiftlang/docs/blob/main/CONTRIBUTING.md) - for guidance on proposing larger content additions. - - - type: dropdown - id: package - attributes: - label: "Target Package" - description: "Which package should contain this new content?" - options: - - API Guidelines - - Language Guides - - Server Guides - - Ecosystem Tools - - New package needed - - Not sure - validations: - required: true - - - type: input - id: location - attributes: - label: "Suggested Location" - description: "Where should this content be added? (chapter, section, or new article)" - placeholder: "e.g., 'Language Guides > Concurrency' or 'New article in Server Guides'" - validations: - required: false + [1]: https://forums.swift.org/c/development/swift-docc/80 - type: textarea id: description attributes: - label: "Content Description" - description: "What should this new documentation cover?" - placeholder: "Provide a clear summary of the proposed content" - validations: - required: true - - - type: textarea - id: motivation - attributes: - label: "Motivation" - description: "Why is this documentation needed?" - placeholder: "What problem does this solve? What audience would benefit?" + label: "What documentation is needed?" + description: >- + Describe the topic and who would benefit validations: required: true diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml deleted file mode 100644 index c2a2311..0000000 --- a/.github/ISSUE_TEMPLATE/enhancement.yml +++ /dev/null @@ -1,58 +0,0 @@ -name: "Enhancement / Improvement" -description: "Suggest improvements to existing documentation (without claiming inaccuracy)" -labels: ["enhancement"] -body: - - type: markdown - attributes: - value: | - Thank you for helping improve the Swift documentation! - - Use this template for: - - Adding examples or code snippets - - Improving clarity or wording - - Restructuring for better flow - - Adding cross-references or links - - If content is factually incorrect, use the "Content Error" template instead. - - - type: input - id: location - attributes: - label: "Location (URL)" - description: "URL of the content to improve" - placeholder: "https://www.swift.org/documentation/..." - validations: - required: true - - - type: dropdown - id: improvement_type - attributes: - label: "Type of Improvement" - description: "What kind of enhancement are you suggesting?" - options: - - Add examples or code samples - - Improve clarity or wording - - Add diagrams or illustrations - - Restructure or reorganize - - Add cross-references or links - - Expand coverage of topic - - Other - validations: - required: true - - - type: textarea - id: current_state - attributes: - label: "Current State" - description: "What does the documentation currently say or show?" - validations: - required: true - - - type: textarea - id: proposed_improvement - attributes: - label: "Proposed Improvement" - description: "How should it be improved?" - placeholder: "Be specific about what you'd like to see added or changed" - validations: - required: true diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml deleted file mode 100644 index 22cbe46..0000000 --- a/.github/ISSUE_TEMPLATE/task.yml +++ /dev/null @@ -1,75 +0,0 @@ -name: "⚙️ Track a Task" -description: "Track internal work, technical debt, or maintenance tasks" -labels: ["task", "triage needed"] -body: - - type: markdown - attributes: - value: | - Tasks track internal work items including: - - Technical debt or maintenance - - Build system or tooling updates - - Documentation infrastructure improvements - - Multi-step work that needs coordination - - For content changes, consider using Content Error, Enhancement, or Content Proposal templates. - - - type: dropdown - id: package - attributes: - label: "Affected Package(s)" - description: "Which packages does this task affect?" - multiple: true - options: - - API Guidelines - - Language Guides - - Server Guides - - Ecosystem Tools - - Repository infrastructure - - All packages - validations: - required: true - - - type: dropdown - id: task_type - attributes: - label: "Task Type" - description: "What kind of task is this?" - options: - - Technical debt - - Build system update - - Tooling improvement - - Infrastructure maintenance - - Process improvement - - Coordination / umbrella issue - - Other - validations: - required: true - - - type: textarea - id: description - attributes: - label: "Description" - description: "A clear description of the task" - placeholder: "Describe what needs to be done and why" - validations: - required: true - - - type: textarea - id: subtasks - attributes: - label: "Subtasks or Checklist" - description: "Break down the work into steps (optional)" - placeholder: | - - [ ] Step 1 - - [ ] Step 2 - - [ ] Step 3 - validations: - required: false - - - type: textarea - id: additional_info - attributes: - label: "Additional Information" - description: "Any context, dependencies, or related issues" - validations: - required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7514462..6cb620f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,33 +1,12 @@ ## Summary - + -## Related Issue - - -Closes: # - - -## Testing - - - -### Build Verification -- [ ] Ran `swift package generate-documentation --analyze --warnings-as-errors` successfully -- [ ] Previewed documentation locally with `swift package --disable-sandbox preview-documentation` - -### Content Review -- [ ] Changes follow the [Apple Style Guide](https://help.apple.com/applestyleguide/) -- [ ] Changes follow [TSPL style guidelines](https://github.com/swiftlang/swift-book/blob/main/Style.md#terms-and-rules) -- [ ] Code examples compile and run as expected -- [ ] Links and cross-references are valid - -## Additional Notes - - +## Validation +- [ ] `swift package generate-documentation --analyze --warnings-as-errors` passes +- [ ] Previewed locally with `swift package --disable-sandbox preview-documentation` --- - -**By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.** +By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.