docs(sage-monorepo): add docs about co-authors (#2523)

Sage-Bionetworks · Feb 23, 2024 · f6dc872 · f6dc872
1 parent a81c5be
commit f6dc872
Show file tree

Hide file tree

Showing 2 changed files with 97 additions and 42 deletions.
diff --git a/docs/developers-guide/creating-a-commit-with-multiple-authors.md b/docs/developers-guide/creating-a-commit-with-multiple-authors.md
@@ -0,0 +1,54 @@
+# Creating a commit with multiple authors
+
+## Introduction
+
+You can attribute a commit to more than one author by adding one or more `Co-authored-by` trailers
+to the commit's message. Co-authored commits are visible on GitHub.
+
+## When to add co-authors to a commit?
+
+Annotating commits with co-authors is required when:
+
+- You are about to commit previously-untracked code written by other users.
+  - Example:
+    1. User A develops a new feature and submits it as a PR.
+    2. User B is tasked with refactoring the PR from User A into multiple PRs.
+    3. User B copy-paste code written by User A and adapt it.
+    4. User B adds User A as a co-author when the commits include code written by User A.
+
+## Adding co-authors to a commit
+
+Follow the instructions described [here](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors).
+
+Preview of the commit creation:
+
+```
+$ git commit -m "Refactor usability tests.
+>
+>
+Co-authored-by: NAME <EMAIL>
+Co-authored-by: ANOTHER-NAME <ANOTHER-EMAIL>"
+```
+
+## Names and emails of Sage Monorepo contributors
+
+The name and "no-reply" emails of the Sage Monorepo contributors (sorted alphabetically):
+
+- Co-authored-by: andrewelamb <[email protected]>
+- Co-authored-by: gaiaandreoletti <[email protected]>
+- Co-authored-by: Lingling <[email protected]>
+- Co-authored-by: mdsage1 <[email protected]>
+- Co-authored-by: Rongrong Chai <[email protected]>
+- Co-authored-by: sagely1 <[email protected]>
+- Co-authored-by: Thomas Schaffter <[email protected]>
+- Co-authored-by: Verena Chung <[email protected]>
+
+> [!NOTE]
+> The names and user ID are collected from the profile page of the contributors. If a contributor
+does not specify their name on the profile page, the listing below uses their GitHub username
+instead of their name. The user ID can be found in the URL of the user's avatar.
+
+## References
+
+- [Creating a commit with multiple
+  authors](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,5 +1,5 @@
 # Project
-site_name: "Sage Monorepo"
+site_name: 'Sage Monorepo'
 site_description: >-
   A development environment for building robust apps faster.
 
@@ -9,57 +9,58 @@ repo_name: sage-monorepo
 
 # Navigation
 nav:
-  - Home: 
-    - Sage Monorepo: index.md
-    - What's new: news.md
-    - Contributing:
-      - Overview: contributions/overview.md
-      - Reporting a bug: contributions/bug-report.md
-      - Adding a feature: contributions/guidelines.md
+  - Home:
+      - Sage Monorepo: index.md
+      - What's new: news.md
+      - Contributing:
+          - Overview: contributions/overview.md
+          - Reporting a bug: contributions/bug-report.md
+          - Adding a feature: contributions/guidelines.md
   - Getting Started:
-    - What is Angular Universal?: getting-started/what-is-angular.md
-    - What is a devcontainer?: getting-started/what-is-devcontainer.md
-    - What is Nx?: getting-started/what-is-nx.md
-    - Setup: 
-      - Develop Locally: getting-started/local-dev.md
-      - Develop On a Remote Host: getting-started/remote-dev.md
+      - What is Angular Universal?: getting-started/what-is-angular.md
+      - What is a devcontainer?: getting-started/what-is-devcontainer.md
+      - What is Nx?: getting-started/what-is-nx.md
+      - Setup:
+          - Develop Locally: getting-started/local-dev.md
+          - Develop On a Remote Host: getting-started/remote-dev.md
   - Tutorials:
-    - Angular:
-      - Create an Angular app: tutorials/angular/add-app.md
-      - Add an Angular API client: tutorials/angular/add-api-client.md
-      - Add an Angular component: tutorials/angular/add-component.md
-      - Add an Angular library: tutorials/angular/add-library.md
-    - Docker:
-      - Create a Docker-based project: tutorials/docker/new-project.md
-    - Java:
-      - Add a Java library: tutorials/java/add-library.md
-      - Add a Java REST API: tutorials/java/add-rest-api.md
-    - Python:
-      - Add a Python REST API: tutorials/python/add-rest-api.md
-    - R:
-      - Add an R project: tutorials/r/new-project.md
+      - Angular:
+          - Create an Angular app: tutorials/angular/add-app.md
+          - Add an Angular API client: tutorials/angular/add-api-client.md
+          - Add an Angular component: tutorials/angular/add-component.md
+          - Add an Angular library: tutorials/angular/add-library.md
+      - Docker:
+          - Create a Docker-based project: tutorials/docker/new-project.md
+      - Java:
+          - Add a Java library: tutorials/java/add-library.md
+          - Add a Java REST API: tutorials/java/add-rest-api.md
+      - Python:
+          - Add a Python REST API: tutorials/python/add-rest-api.md
+      - R:
+          - Add an R project: tutorials/r/new-project.md
   - Developers Guide:
-    - Common Issues: developers-guide/faq.md
+      - Creating a commit with multiple authors: developers-guide/creating-a-commit-with-multiple-authors.md
+      - Common Issues: developers-guide/faq.md
   - Reference:
-    - Agora:
-      - API: reference/agora.md
-    - OpenChallenges:
-      - Microservices: reference/oc-microservices.md
-      - Schemas: reference/oc-schemas.md
-    - Schematic:
-      - API: reference/schematic.md
+      - Agora:
+          - API: reference/agora.md
+      - OpenChallenges:
+          - Microservices: reference/oc-microservices.md
+          - Schemas: reference/oc-schemas.md
+      - Schematic:
+          - API: reference/schematic.md
 
 # Theme configuration
 theme:
   name: material
   palette:
-    - media: "(prefers-color-scheme: light)" 
+    - media: '(prefers-color-scheme: light)'
       scheme: default
       primary: blue
       toggle:
         icon: material/toggle-switch-off-outline
         name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)" 
+    - media: '(prefers-color-scheme: dark)'
       scheme: slate
       primary: blue
       toggle:
@@ -81,10 +82,10 @@ theme:
     - toc.follow
 
 plugins:
-- search
-- mkdocstrings
-- autorefs
-- termynal
+  - search
+  - mkdocstrings
+  - autorefs
+  - termynal
 
 markdown_extensions:
   - admonition