PR#74: team directory prototype - Fedora-Council/council-docs

Fedora-Council / council-docs

#74 team directory prototype

Merged 3 years ago by bcotton. Opened 3 years ago by asamalik.

Fedora-Council/ asamalik/council-docs team-directory into master

team directory prototype

Adam Samalik • 3 years ago

ef4b873

engineering/antora.yml

file added

+16

		`@@ -0,0 +1,16 @@`
		`+ # Name will be mostly visible in the URL. Treat it as an indentifier.`
		`+ # Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)`
		`+ name: engineering # <---- PLEASE MODIFY`
		`+`
		`+ # Title will be visible on the page.`
		`+ title: Engineering Teams # <---- PLEASE MODIFY`
		`+`
		`+ # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.`
		`+ version: master`
		`+`
		`+ # We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise.`
		`+ start_page: ROOT:index`
		`+`
		`+ # This lists all the menu definitions of your component.`
		`+ #nav:`
		`+ #- modules/ROOT/nav.adoc`

engineering/modules/ROOT/pages/index.adoc

file added

+58

		`@@ -0,0 +1,58 @@`
		`+ = Fedora Engineering`
		`+ :page-layout: without_menu`
		`+`
		`+ xref:fesco:ROOT:index.adoc[Fedora Engineering Steering Committee] — FESCo is the Fedora Engineering Steering Committee. It is a fully community elected body and represents the technical leadership in Fedora.`
		`+`
		`+ == Engineering Teams`
		`+`
		`+ // Include individual team entries as follows:`
		`+ // include::COMPONENT:MODULE:partial$FILENAME.adoc[]`
		`+ // include::partial$team_render.adoc[]`
		`+ //`
		`+ // Or if it's a local file:`
		`+ // include::partial$FILENAME.adoc[]`
		`+ // include::partial$team_render.adoc[]`
		`+`
		`+`
		`+ // Example 1: A team entry using data stored in a different space`
		`+`
		`+ // The Template Team`
		`+ include::engineering:ROOT:partial$TEMPLATE_team_info.adoc[]`
		`+ include::partial$team_render.adoc[]`
		`+`
		`+`
		`+ // Example 2: A team entry using data stored in this repository (using the template)`
		`+`
		`+ // The Template Team`
		`+ include::partial$TEMPLATE_team_info.adoc[]`
		`+ include::partial$team_render.adoc[]`
		`+`
		`+`
		`+`
		`+ // Old entries:`
		`+ * xref:modularity:ROOT:index.adoc[Fedora Modularity] — Modularity introduces an optional Modular repository that provides additional versions of software on independent lifecycles.`
		`+`
		`+ * xref:containers:ROOT:index.adoc[Fedora Containers] — Here you will find Documentation and Guidelines regarding creation, usage and maintainance of Containers in Fedora.`
		`+`
		`+ * xref:neurofedora:ROOT:overview.adoc[NeuroFedora] — NeuroFedora is an initiative to provide a ready to use Fedora based Free/Open source software platform for neuroscience.`
		`+`
		`+ * xref:teleirc-sig:ROOT:index.adoc[Fedora Teleirc SIG] — The Teleirc SIG is a volunteer-driven group to manage Teleirc bridge bots.`
		`+`
		`+ * xref:ci:ROOT:index.adoc[Fedora CI] — Fedora Continuous Integration Portal`
		`+`
		`+ * link:https://fedora-infra-docs.readthedocs.io/en/latest/[Fedora Infrastructure 🔗] — Documentation covering the development and administration of the many projects that make Fedora work.`
		`+`
		`+ * xref:qa-docs:ROOT:index.adoc[Fedora QA] — This docs outlines all the activities you can get involved in to help with Fedora QA (Quality Assurance) and is meant to guide you through the QA ecosystem.`
		`+`
		`+ * xref:cpe:ROOT:index.adoc[CPE] - The Community Platform Engineering Team is a Red Hat team dedicated to the Fedora and CentOS projects where they contribute to the infrastructure and release engineering.`
		`+`
		`+ == Other Engineering Resources`
		`+ ////`
		`+ Because this page has already existed and linked to other spaces`
		`+ that not necessarily represent teams, we have this category to keep those`
		`+ so people can still find them.`
		`+ ////`
		`+`
		`+ * xref:flatpak:ROOT:index.adoc[Flatpak in Fedora] — Learn how to build Flatpaks out of Fedora RPM packages.`
		`+`
		`+ * xref:minimization:ROOT:index.adoc[Fedora Minimization Objective] — Home of the Fedora Minimization Objective.`

engineering/modules/ROOT/partials/TEMPLATE_team_info.adoc

file added

+35

		`@@ -0,0 +1,35 @@`
		`+ // TEMPLATE`
		`+`
		`+ // This is a data store of information about a Fedora team.`
		`+`
		`+ // File like this would be stored either in the team's docs`
		`+ // git repository, or if they don't have any (maybe they live on a wiki).`
		`+ // then it can be stored in the council-docs repo next to the template.`
		`+`
		`+ // Team name:`
		`+ :team_name: Team Name`
		`+`
		`+ // Team summary:`
		`+ :team_summary: We serve as a template.`
		`+`
		`+ // Team page URL:`
		`+ :team_url: https://docs.fedoraproject.org/en-US/council/`
		`+`
		`+ // Team activity status.`
		`+ // Choose from: Active, Inactive`
		`+ :team_status: Active`
		`+`
		`+ // Preferred Asynch communication channel (mailing list, discussion.fp.o, none, etc)`
		`+ :team_asynch_communication: https://lists.fedoraproject.org/admin/lists/council-discuss.lists.fedoraproject.org/`
		`+`
		`+ // Preferred Synch (IRC channel, telegram, etc, none)`
		`+ :team_synch_communication: #fedora-council`
		`+`
		`+ // Issue tracker`
		`+ :team_issue_tracker: https://pagure.io/Fedora-Council/tickets`
		`+`
		`+ // Meetings`
		`+ :team_meetings: https://fedoraproject.org/wiki/Council_Meetings`
		`+`
		`+ // Any other information?`
		`+ :team_other: Lorem ipsum`
		`\ No newline at end of file`

engineering/modules/ROOT/partials/team_render.adoc

file added

		`@@ -0,0 +1,1 @@`
		`+ * {team_url}[{team_name}] — {team_summary}`
		`\ No newline at end of file`

mindshare/antora.yml

file added

+16

		`@@ -0,0 +1,16 @@`
		`+ # Name will be mostly visible in the URL. Treat it as an indentifier.`
		`+ # Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)`
		`+ name: mindshare # <---- PLEASE MODIFY`
		`+`
		`+ # Title will be visible on the page.`
		`+ title: Mindshare Teams # <---- PLEASE MODIFY`
		`+`
		`+ # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.`
		`+ version: master`
		`+`
		`+ # We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise.`
		`+ start_page: ROOT:index`
		`+`
		`+ # This lists all the menu definitions of your component.`
		`+ #nav:`
		`+ #- modules/ROOT/nav.adoc`

mindshare/modules/ROOT/pages/index.adoc

file added

+51

		`@@ -0,0 +1,51 @@`
		`+ = Fedora Mindshare`
		`+ :page-layout: without_menu`
		`+`
		`+ Mindshare Teams are focused on helping our community grow both the number of users and contributors. The teams in Mindshare are each focused on a different aspect of this goal.`
		`+`
		`+ xref:mindshare-committee:ROOT:index.adoc[Fedora Mindshare Committee] — The Mindshare Committee fosters communication amongst the Mindshare teams and helps facilitate Council strategy.`
		`+`
		`+ == Mindshare Teams`
		`+`
		`+ // Include individual team entries as follows:`
		`+ // include::COMPONENT:MODULE:partial$FILENAME.adoc[]`
		`+ // include::partial$team_render.adoc[]`
		`+ //`
		`+ // Or if it's a local file:`
		`+ // include::partial$FILENAME.adoc[]`
		`+ // include::partial$team_render.adoc[]`
		`+`
		`+`
		`+ // Example 1: A team entry using data stored in a different space`
		`+`
		`+ // The Template Team`
		`+ include::mindshare:ROOT:partial$TEMPLATE_team_info.adoc[]`
		`+ include::partial$team_render.adoc[]`
		`+`
		`+`
		`+ // Example 2: A team entry using data stored in this repository (using the template)`
		`+`
		`+ // The Template Team`
		`+ include::partial$TEMPLATE_team_info.adoc[]`
		`+ include::partial$team_render.adoc[]`
		`+`
		`+`
		`+`
		`+ // Old entries:`
		`+ * xref:commops:ROOT:index.adoc[Fedora Community Operations (CommOps)] — Community Operations (CommOps) provides tools, resources, and utilities for different sub-projects of Fedora to improve effective communication.`
		`+`
		`+ * xref:fedora-docs:ROOT:index.adoc[Fedora Documentation (Docs)] — The group behind this very documentation site. Includes contributors' guidelines to Fedora Docs`
		`+`
		`+ * xref:badges:ROOT:index.adoc[Fedora Badges] — The group behind Fedora Badges — a fun website built to recognize contributors to the Fedora Project, help new and existing Fedora contributors find different ways to get involved, and encourage the improvement of Fedora's infrastructure.`
		`+`
		`+ * xref:fedora-magazine:ROOT:index.adoc[Fedora Magazine] — Guidelines around contributing to the Fedora Magazine.`
		`+`
		`+ * xref:websites:ROOT:index.adoc[Fedora Websites] - Documentation covering maintenance and expansion of Fedora Project websites.`
		`+`
		`+ * xref:fedora-join:ROOT:index.adoc[Fedora Join SIG] - The Fedora Join SIG aims to set up and maintain channels that let prospective contributors engage with the community.`
		`+`
		`+ * xref:ask-fedora-sops:ROOT:index.adoc[Ask Fedora SOPs] - Standard operating procedures for the link:https://ask.fedoraproject.org/[Ask Fedora forums].`
		`+`
		`+ * xref:localization:ROOT:index.adoc[Fedora Localization Project] - The Fedora Localization Project.`
		`+`
		`+ * xref:docs-l10n:ROOT:index.adoc[Fedora Docs Localization Stats] - Statistics about the Fedora documentation localization progress.`

mindshare/modules/ROOT/partials/TEMPLATE_team_info.adoc

file added

+35

		`@@ -0,0 +1,35 @@`
		`+ // TEMPLATE`
		`+`
		`+ // This is a data store of information about a Fedora team.`
		`+`
		`+ // File like this would be stored either in the team's docs`
		`+ // git repository, or if they don't have any (maybe they live on a wiki).`
		`+ // then it can be stored in the council-docs repo next to the template.`
		`+`
		`+ // Team name:`
		`+ :team_name: Team Name`
		`+`
		`+ // Team summary:`
		`+ :team_summary: We serve as a template.`
		`+`
		`+ // Team page URL:`
		`+ :team_url: https://docs.fedoraproject.org/en-US/council/`
		`+`
		`+ // Team activity status.`
		`+ // Choose from: Active, Inactive`
		`+ :team_status: Active`
		`+`
		`+ // Preferred Asynch communication channel (mailing list, discussion.fp.o, none, etc)`
		`+ :team_asynch_communication: https://lists.fedoraproject.org/admin/lists/council-discuss.lists.fedoraproject.org/`
		`+`
		`+ // Preferred Synch (IRC channel, telegram, etc, none)`
		`+ :team_synch_communication: #fedora-council`
		`+`
		`+ // Issue tracker`
		`+ :team_issue_tracker: https://pagure.io/Fedora-Council/tickets`
		`+`
		`+ // Meetings`
		`+ :team_meetings: https://fedoraproject.org/wiki/Council_Meetings`
		`+`
		`+ // Any other information?`
		`+ :team_other: Lorem ipsum`
		`\ No newline at end of file`

mindshare/modules/ROOT/partials/team_render.adoc

file added

		`@@ -0,0 +1,1 @@`
		`+ * {team_url}[{team_name}] — {team_summary}`
		`\ No newline at end of file`

preview.sh

file modified

+9 -4

		`@@ -1,17 +1,22 @@`
		`#!/bin/sh`

		`+ echo ""`
		`+ echo "The preview is available at http://localhost:8080"`
		`+ echo ""`
		`+ echo "Spaces:"`
		`+ echo " * Project ........ http://localhost:8080/project/"`
		`+ echo " * Council ........ http://localhost:8080/council/"`
		`+ echo " * Engineering .... http://localhost:8080/engineering/"`
		`+ echo " * Mindshare ...... http://localhost:8080/mindshare/"`
		`+`
		`if [ "$(uname)" == "Darwin" ]; then`
		`# Running on macOS.`
		`# Let's assume that the user has the Docker CE installed`
		`# which doesn't require a root password.`
		`- echo "The preview will be available at http://localhost:8080/"`
		`docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx`

		`elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then`
		`# Running on Linux.`
		`# Fedora Workstation has python3 installed as a default, so using that`
		`- echo ""`
		`- echo "The preview is available at http://localhost:8080"`
		`- echo ""`
		`python3 -m http.server --directory ./public 8080`
		`fi`

site.yml

file modified

+12 -6

		`@@ -3,12 +3,18 @@`
		`start_page: council::index`
		`content:`
		`sources:`
		`- - url: .`
		`- branches: HEAD`
		`- start_path: council`
		`- - url: .`
		`- branches: HEAD`
		`- start_path: project`
		`+ - url: .`
		`+ branches: HEAD`
		`+ start_path: council`
		`+ - url: .`
		`+ branches: HEAD`
		`+ start_path: project`
		`+ - url: .`
		`+ branches: HEAD`
		`+ start_path: engineering`
		`+ - url: .`
		`+ branches: HEAD`
		`+ start_path: mindshare`
		`ui:`
		`bundle:`
		`url: https://asamalik.fedorapeople.org/ui-bundle.zip`

asamalik commented 3 years ago

Implementing https://pagure.io/Fedora-Council/tickets/issue/295

Let me explain what I did:

I've copied the sources of the two following pages to this repo:
Mindshare Teams
Engineering Teams

... we'll reuse those as the team directories. When we're ready, I switch the docs to use these sources instead of the original ones for these pages.

Added a file TEMPLATE_team_info.adoc — a template of a data store for each team's information. Each team will store their own copy either in their docs git, or here or somewhere if they don't have one. Council representatives then include those in the pages. There are examples in the sources already, but each entry will look like this:

// The Template Team
include::mindshare:ROOT:partial$TEMPLATE_team_info.adoc[]
include::partial$team_render.adoc[]

The file team_renderer.adoc defines how each entry is rendered.

Teams will be also able to include their data store on any page, and use {team_name}, {team_description}, etc. wherever they want to.

Not sure if it's not too complicated. As an alternative, we could also just keep the format of the team pages as it is right now, and just make sure the council representatives keep them up-to-date.

What do people think?

bcotton commented 3 years ago

I like the general concept. My main concern is that we have the template duplicated in two places, which means if we ever want to change it we have to change it in two places. I wonder if we'd be better off having a canonical location that the instructions say (copy this from). Or maybe I'm worrying about a problem that won't really be much of a problem.

I'd also suggest adding the basics of the communication channels to the team_render.adoc so that folks can see it at a glance.

I'm interested to see what others think as well.