Documentation Guidelines, Contributing Guidelines, and GitHub Discussions

.github/DISCUSSION_TEMPLATE/spezi.yml → .github/DISCUSSION_TEMPLATE/challenges-and-help.yml

@@ -6,13 +6,13 @@
 # SPDX-License-Identifier: MIT
 #
 
-title: "[Stanford Spezi] "
-labels: ["Stanford Spezi"]
+title: "Challenges and Help"
+labels: ["Challenges and Help"]
 body:
   - type: markdown
     attributes:
       value: |
-        Please use this form to describe your Stanford Spezi-related question.
+        Thanks for taking the time to share any questions or challenges you have with a Stanford Spezi module!
   - type: dropdown
     attributes:
       label: What Stanford Spezi module is your challenge related to?
@@ -24,6 +24,7 @@ body:
         - SpeziFirebase
         - SpeziHealthKit
         - SpeziLocalStorage
+        - SpeziML
         - SpeziOnboarding
         - SpeziQuestionnaire
         - SpeziScheduler

.github/DISCUSSION_TEMPLATE/ideas.yml

@@ -6,13 +6,32 @@
 # SPDX-License-Identifier: MIT
 #
 
-title: "[Ideas] "
+title: "Ideas"
 labels: ["Ideas"]
 body:
   - type: markdown
     attributes:
       value: |
         Thanks for taking the time to share your improvement idea!
+  - type: dropdown
+    attributes:
+      label: What Stanford Spezi module is your idea related to?
+      options:
+        - Spezi
+        - SpeziAccount
+        - SpeziContact
+        - SpeziFHIR
+        - SpeziFirebase
+        - SpeziHealthKit
+        - SpeziLocalStorage
+        - SpeziML
+        - SpeziOnboarding
+        - SpeziQuestionnaire
+        - SpeziScheduler
+        - SpeziStorage
+        - SpeziViews
+        - SpeziTemplateApplication
+        - Other module
   - type: textarea
     id: usecase
     attributes:

.github/DISCUSSION_TEMPLATE/show-and-tell.yml

@@ -6,7 +6,7 @@
 # SPDX-License-Identifier: MIT
 #
 
-title: "[Show and Tell] "
+title: "Show and Tell"
 labels: ["Show and Tell"]
 body:
   - type: markdown

.github/pull_request_template.md

@@ -11,29 +11,25 @@ SPDX-License-Identifier: MIT
 # *Name of the PR*
 
 ## :recycle: Current situation & Problem
-*Describe the current situation (if possible, with an exemplary (or real) code snippet and/or where this is used)*
-*Please link any open issue that is addressed with this PR*
+*Link any open issues or pull requests (PRs) related to this PR. Please ensure that all non-trivial PRs are first tracked and discussed in an existing GitHub issue or discussion.*
 
-## :bulb: Proposed solution
-*Describe the solution and how this affects the project and internal structure*
 
 ## :gear: Release Notes 
-*Add a summary of the feature and possible migration guides if this is a breaking change so this section can be added to the release notes.*
-*Include code snippets that provide examples of the feature implemented if it appends or changes the public interface.*
+*Add a bullet point list summary of the feature and possible migration guides if this is a breaking change so this section can be added to the release notes.*
+*Include code snippets that provide examples of the feature implemented or links to the documentation if it appends or changes the public interface.*
 
-## :heavy_plus_sign: Additional Information
-*Provide some additional information if possible*
 
-### Related PRs
-*Reference the related PRs*
+## :books: Documentation
+*Please ensure that you properly document any additions in conformance to [Spezi Documentation Guide](https://github.com/StanfordSpezi/.github/blob/main/DocumentationGuide.md).*
+*You can use this section to describe your solution, but we encourage contributors to document your reasoning and changes using in-line documentation.* 
 
-### Testing
-*Are there tests included? If yes, which situations are tested, and which corner cases are missing?*
 
-### Reviewer Nudging
-*Where should the reviewer start? Where is a good entry point?*
+## :white_check_mark: Testing
+*Please ensure that the PR meets the testing requirements set by CodeCov and that new functionality is appropriately tested.*
+*This section describes important information about the tests and why some elements might not be testable.*
 
-### Code of Conduct & Contributing Guidelines 
+
+## :pencil: Code of Conduct & Contributing Guidelines 
 
 By submitting creating this pull request, you agree to follow our [Code of Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md):
 - [ ] I agree to follow the [Code of Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md).

CONTRIBUTING.md

@@ -12,23 +12,33 @@ SPDX-License-Identifier: MIT
 
 Thank you for contributing to the Stanford Spezi open-source project! We value the time and effort you invest in the open-source project!
 
-We use [GitHub Discussions](https://docs.github.com/en/discussions) at [https://github.com/orgs/StanfordSpezi/discussions](https://github.com/orgs/StanfordSpezi/discussions) for any discussions about the project.
-Please follow our [Code of Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md).
+The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
 
-We use the [Github Flow](https://guides.github.com/introduction/flow/index.html) for all code-related contributions.
-GitHub discussions are the best way to brainstorm your suggestions. 
-GitHub issues are the best way to document decisions or bugs.
-Pull requests are the best way to propose changes to the codebase.
+We REQUIRED using [GitHub Discussions](https://docs.github.com/en/discussions) at [https://github.com/orgs/StanfordSpezi/discussions](https://github.com/orgs/StanfordSpezi/discussions) for any discussions about the project.
+You MUST follow our [Code of Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md).
+
+We REQUIRED using the [Github Flow](https://guides.github.com/introduction/flow/index.html) for all code-related contributions.
+GitHub discussions SHALL be the best way to brainstorm your suggestions. 
+GitHub issues SHALL be the best way to document decisions or bugs.
+Pull requests SHALL be the best way to propose changes to the codebase.
+
+## Documentation
+
+All documentation MUST conform to our [Documentation Guide](https://github.com/StanfordSpezi/.github/blob/main/DocumentationGuide.md)
+
+## Testing
+
+Every new contribution MUST be properly tested and automatically verified using unit tests, user interface (UI) tests, and our continuous integration (CI) setup using GitHub Actions.
 
 ## Licensing
 
-Your submissions must be published and conform to the license currently used in the respective repository.
+Your submissions MUST be published and conform to the license currently used in the respective repository.
 
 ## Attributions
 
 We use the [REUSE Software Conventions](https://reuse.software) to structure our attributions and contributor lists.
 
-Each file must contain the following header information with `Spezi` being replaced with the project name and [`MIT` with the SPDX License Identifier](https://spdx.org/ids).
+Each file MUST contain the following header information with `Spezi` being replaced with the project name and [`MIT` with the SPDX License Identifier](https://spdx.org/ids).
 ```
 This source file is part of the Stanford Spezi open-source project
 
@@ -38,13 +48,14 @@ SPDX-License-Identifier: MIT
 ```
 
 As referenced in the copyright text, we list all contributors in the CONTRIBUTORS.md at the root of every repository.
-Each contributor can add themselves to the CONTRIBUTORS.md in a pull request with a sizable and meaningful contribution to the project.
+Each contributor SHOULD add themselves to the CONTRIBUTORS.md in a pull request with a sizable and meaningful contribution to the project.
+The addition and final decision to be added to the CONTRIBUTORS.md is up to the Spezi core team.
 
-If your code is based on another source, you must add a reference to the original source code to the specific code (e.g., using a comment) and make sure that the license of the original source allows the usage under the license used in the project.
+If your code is based on another source, you MUST add a reference to the original source code to the specific code (e.g., using a comment) and make sure that the license of the original source allows the usage under the license used in the project.
 
 ## Bug Reporting
 
-We use GitHub issues to track work items. Report a bug by opening a new issue using the bug issue template.
+We use GitHub issues to track work items. Report a bug SHALL be done by opening a new issue using the bug issue template.
 
 ## Support Policy
 

DocumentationGuide.md

@@ -0,0 +1,134 @@
+<!--
+
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT
+
+-->
+
+# Documentation Guide
+
+This document defines the documentation requirement for a Spezi Module and hints and examples on how to best structure your documentation.
+The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+The README and documentation of the [SpeziMockWebService module](https://github.com/StanfordSpezi/SpeziMockWebService) are good examples of how documentation can be structured and written.
+
+
+## Code Documentation
+
+Serves as general guidance for writing documentation.
+All public interfaces of a Spezi module MUST be documented with non-trivial documentation that SHOULD guide a wide variety of users on how to use the application programming interface (API).
+
+Text MUST be written in a neutral form in conformance to the [contribution guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md) and the [contributor covenant code of conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md).
+Abbreviations SHOULD be expanded the first time they are used.
+Inline documentation SHOULD have real-world examples and links to relevant information outside of the Spezi ecosystem to read up on important concepts.
+
+The documentation MUST use appropriate [GitHub markdown syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) and [DocC documentation formatting elements](https://www.swift.org/documentation/docc/formatting-your-documentation-content) to create documentation that is easy to understand and well structured. 
+
+Related types within the module MUST be linked using [markdown links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links) or [DocC links](https://www.swift.org/documentation/docc/formatting-your-documentation-content#Link-to-Symbols-and-Other-Content).
+Essential external types SHOULD be linked to, e.g., the Apple Documentation like the [`@State`](https://developer.apple.com/documentation/swiftui/state) property wrapper.
+
+Code examples MUST use the proper syntax highlighting.
+
+Elements like [notes and other asides](https://www.swift.org/documentation/docc/documenting-a-swift-framework-or-package) SHOULD be used.
+GitHub offers equal elements for README documents, e.g.:
+```md
+> [!IMPORTANT] 
+> An important element ...
+```
+
+
+### Images
+
+All images MUST be available in dark and light mode.
+The document MUST be configured to automatically load the appropriate image, e.g., in markdown using
+```md
+![Example Image](https://raw.githubusercontent.com/StanfordSpezi/.github/main/Example.png#gh-light-mode-only)
+![Example Image](https://raw.githubusercontent.com/StanfordSpezi/.github/main/Example~dark.png#gh-dark-mode-only)
+```
+and using the [DocC Image naming schemes](https://developer.apple.com/documentation/docc/image#Provide-Image-Variants).
+
+User interface screenshots MUST include a device frame, e.g., using [ControlRoom](https://github.com/twostraws/ControlRoom) or other software solutions. The background of the images MUST be transparent to use the background color of the documentation document or README.
+
+
+### Landing Page
+
+The [landing page](https://www.swift.org/documentation/docc/documenting-a-swift-framework-or-package) of the documentation in DocC MUST contain an overview section.
+The overview section MUST include a compact package description and its core functionality.
+A developer MAY use bullet points, a table, or a textual description.
+
+If the module provides significant user interface (UI) components, it SHOULD display them in the README to provide visual guidance.
+The overview SHOULD include a graphical representation of the package's functionality, e.g., a UML diagram or some other visual guidance.
+
+The landing page MAY also include a code example.
+It MUST link to the main types relevant to the Spezi module and SHOULD provide some guidance to articles that guide the user to learn more about the module.
+
+
+## README
+
+The README of a Spezi Module is an essential first point of contact.
+It MUST include the following sections:
+- Header
+- Overview
+- Example
+- Footer
+A README may include additional sections after the overview and before the Footer section.
+The README SHOULD reuse the content of the landing page DocC documentation of the Spezi module. It MAY add context relevant to the GitHub repository compared to the automatically generated documentation.
+
+
+### Header
+
+The Header MUST display the most essential documentation for a Spezi Module, including:
+- GitHub badge to a GitHub Action verifying the current build status
+- CodeCov code coverage report
+- One-line description of the module.
+
+It is RECOMMENDED to include a:
+- DOI for scientific citations, e.g., using [Zenodo.org](zenodo.org)
+- Badges to the [Swift Package Index](https://swiftpackageindex.com) for Swift package-based Spezi modules to indicate the supported Swift version and operating systems.
+
+
+### Overview
+
+The overview section MUST be equivalent to the landing page overview section of the DocC documentation.
+It MAY make slight modifications to adjust for the different formatting possibilities.
+DocC links MUST be translated into links to the hosted documentation, e.g., on the [Swift Package Index](https://swiftpackageindex.com) using markdown links.
+
+
+### Example
+
+The example section MUST include one or more code examples or short guidance on using the Spezi Module.
+The examples MAY be taken out of the inline documentation or articles in the DocC documentation.
+It MUST provide some written guidance around the example.
+The example MUST provide a link to more information about the place where the documentation is hosted, e.g., on the [Swift Package Index](https://swiftpackageindex.com).
+
+E.g., a final sentence MAY look like this:
+```md
+For more information, please refer to the [API documentation](https://swiftpackageindex.com/StanfordSpezi/SpeziMockWebService/documentation).
+```
+
+### Footer
+
+The footer of all Spezi Modules MUST include a link to the contributing guidlines, code of conduct, and license information.
+All Spezi modules hosted in the StanfordSpezi GitHub organization MUST include the footer below.
+Other Spezi modules MAY use the same footer but MUST adjust it to link to their documents, e.g., contributing guidelines.
+```md
+## Contributing
+
+Contributions to this project are welcome. Please make sure to read the [contribution guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md) and the [contributor covenant code of conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md) first.
+
+
+## License
+
+This project is licensed under the MIT License. See [Licenses](https://github.com/StanfordSpezi/SpeziContact/tree/main/LICENSES) for more information.
+
+![Spezi Footer](https://raw.githubusercontent.com/StanfordSpezi/.github/main/assets/Footer.png#gh-light-mode-only)
+![Spezi Footer](https://raw.githubusercontent.com/StanfordSpezi/.github/main/assets/Footer~dark.png#gh-dark-mode-only)
+```
+
+## Further Details
+
+GitHub repository SHOULD include the main description of the Spezi module and SHOULD link to the hosted documentation, e.g., at the [Swift Package Index](https://swiftpackageindex.com) in the sidebar of the GitHub repo.
+GitHub tags like `Spezi` and others MAY be used to easily find the module on GitHub or the [Swift Package Index](https://swiftpackageindex.com).

assets/Footer.png.license

@@ -0,0 +1,5 @@
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT

assets/Footer~dark.png.license

@@ -0,0 +1,5 @@
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT

profile/README.md

@@ -14,7 +14,9 @@ SPDX-License-Identifier: MIT
 
 To get started with Spezi, try our [Template Application](https://github.com/StanfordSpezi/SpeziTemplateApplication)!
 
+We are always looking for open source collaborators. Please take a look at the [Code of Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md) for more information.
 For more information, check out our website at [spezi.stanford.edu](https://spezi.stanford.edu).
 
-![Spezi Footer](https://raw.githubusercontent.com/StanfordSpezi/.github/main/assets/FooterLight.png#gh-light-mode-only)
-![Spezi Footer](https://raw.githubusercontent.com/StanfordSpezi/.github/main/assets/FooterDark.png#gh-dark-mode-only)
+
+![Spezi Footer](https://raw.githubusercontent.com/StanfordSpezi/.github/main/assets/Footer.png#gh-light-mode-only)
+![Spezi Footer](https://raw.githubusercontent.com/StanfordSpezi/.github/main/assets/Footer~dark.png#gh-dark-mode-only)