add readme for editing

MDAnalysis · Nov 4, 2023 · d99f059 · d99f059
1 parent 7947c78
commit d99f059
Show file tree

Hide file tree

Showing 14 changed files with 56 additions and 13 deletions.
diff --git a/_data/team/roles/README.md b/_data/team/roles/README.md
@@ -0,0 +1,43 @@
+# Roles
+
+This directory contains YAML files, one per role.
+
+## Editing
+
+Each YAML file should contain the details of one role only.
+Each role is automatically picked up by the template. To add or remove a role, simply add or remove a file. Do not add non-role documents to this directory that can be parsed by Jekyll.
+
+Each file *must* contain the following tags at top level:
+
+* `role`: The name of the role (e.g. Core library maintenance)
+
+Each role can optionally have the following tags:
+* `description`: text describing the role. This can be written in Markdown.
+* `tasks`: a list of strings describing tasks. This is rendered as a list.
+
+Each role can also optionally have lead/member tags, if there are no subroles. If there are subroles, the below are ignored:
+* `current_leads`: a list of names who are current leads
+* `current_members`: a list of names who are current members in the subgroup
+* `historical_leads`: a list of names who were previously leads
+* `historical_members`: a list of names who were previously members in the subgroup
+
+Onto subroles: each role can optionally define `subroles`. The `subroles` tag should be a **list** where each item *must have*:
+
+* `subrole`: The name of the subrole (e.g. Issue management)
+
+Each subrole can *optionally have*:
+* `current_leads`: a list of names who are current leads
+* `current_members`: a list of names who are current members in the subgroup
+* `historical_leads`: a list of names who were previously leads
+* `historical_members`: a list of names who were previously members in the subgroup
+* `description`: text describing the role. This can be written in Markdown.
+* `tasks`: a list of strings describing tasks. This is rendered as a list.
+
+
+## Parsing
+
+The files here are read first by ``_includes/team_table.html`` and ``_includes/roles_description.html``.
+Jekyll automatically reads YAML, JSON, and other formatted files in the ``_data`` directory
+as objects that can be interacted with using the Liquid templating language.
+For example, the ``name`` variable of the ``code_of_conduct.yml`` file is accessible as ``site.data.team.roles.code_of_conduct.name`` in HTML.
+
diff --git a/_data/team/roles/code_of_conduct.yml b/_data/team/roles/code_of_conduct.yml
@@ -14,4 +14,4 @@ historical_leads:
   - Jenna Swarthout Goddard
   - Richard Gowers
   - Micaela Matta
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/community_engagement.yml b/_data/team/roles/community_engagement.yml
@@ -9,4 +9,4 @@ current_members:
 historical_leads:
   - Oliver Beckstein
   - Irfan Alibay
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/continuous_integration.yml b/_data/team/roles/continuous_integration.yml
@@ -10,4 +10,4 @@ current_members:
   - Fiona Naughton
 historical_leads:
   - Irfan Alibay
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/core_library_maintenance.yml b/_data/team/roles/core_library_maintenance.yml
@@ -47,4 +47,4 @@ subroles:
     historical_leads:
       - Irfan Alibay
       - Jonathan Barnoud
-    historical_members: []
+    historical_members: []
diff --git a/_data/team/roles/documentation.yml b/_data/team/roles/documentation.yml
@@ -15,4 +15,4 @@ current_members:
 historical_leads:
   - Irfan Alibay
   - Lily Wang
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/external_liaison.yml b/_data/team/roles/external_liaison.yml
@@ -10,4 +10,4 @@ current_members:
   - Jenna Swarthout Goddard
 historical_leads:
   - Irfan Alibay
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/governance.yml b/_data/team/roles/governance.yml
@@ -15,4 +15,4 @@ historical_leads:
   - Oliver Beckstein
   - Irfan Alibay
   - Jenna Swarthout Goddard
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/mdakit_registry.yml b/_data/team/roles/mdakit_registry.yml
@@ -12,4 +12,4 @@ current_members:
   - Oliver Beckstein
 historical_leads:
   - Irfan Alibay
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/non_core_library_maintenance.yml b/_data/team/roles/non_core_library_maintenance.yml
@@ -77,4 +77,4 @@ subroles:
     current_members: []
     historical_leads:
       - Irfan Alibay
-    historical_members: []
+    historical_members: []
diff --git a/_data/team/roles/outreach.yml b/_data/team/roles/outreach.yml
@@ -29,4 +29,4 @@ subroles:
     historical_leads:
       - Jenna Swarthout Goddard
       - Oliver Beckstein
-    historical_members: []
+    historical_members: []
diff --git a/_data/team/roles/releases_and_deployment.yaml b/_data/team/roles/releases_and_deployment.yaml
@@ -12,4 +12,4 @@ current_members:
   - Fiona Naughton
 historical_leads:
   - Irfan Alibay
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/relicensing_coordinator.yml b/_data/team/roles/relicensing_coordinator.yml
@@ -11,4 +11,4 @@ current_leads:
 current_members: []
 historical_leads:
   - Irfan Alibay
-historical_members: []
+historical_members: []
diff --git a/_data/team/roles/social_media.yml b/_data/team/roles/social_media.yml
@@ -11,4 +11,4 @@ current_members: []
 historical_leads:
   - Oliver Beckstein
   - Jenna Swarthout Goddard
-historical_members: []
+historical_members: []