From 6c34642374bc0851fc4505cfa2441de59417d6bd Mon Sep 17 00:00:00 2001 From: Justin W. Flory Date: Sep 10 2018 23:48:30 +0000 Subject: [PATCH 1/2] Minor content revisions, more xrefs replace URLs, drop statscache This commit makes minor content revisions and corrections, moves more cross-document linking from hard-coded URLs to internal Antora anchors, and removes statscache from the CommOps toolbox, since it is likely to go away in the near future. Actual changes to source content were kept minimal, other than a slight modernization to current times. More unique content change will come in later PRs. --- diff --git a/docs/modules/ROOT/pages/community-blog.adoc b/docs/modules/ROOT/pages/community-blog.adoc index 0a54a13..e036861 100644 --- a/docs/modules/ROOT/pages/community-blog.adoc +++ b/docs/modules/ROOT/pages/community-blog.adoc @@ -2,7 +2,7 @@ include::{partialsdir}/attributes.adoc[] = Community Blog -The https://communityblog.fedoraproject.org[Fedora Community Blog] (CommBlog) is a WordPress-based site that delivers news, updates, and calls for help from contributors across Fedora. +The {COMMBLOG}[Fedora Community Blog] (CommBlog) is a WordPress-based site that delivers news, updates, and calls for help from contributors across Fedora. image::https://fedoraproject.org/w/uploads/0/09/Community_Blog_screenshot.png[Community Blog screenshot,90%,90%] @@ -54,7 +54,7 @@ Short snippets are useful too. If you're not sure how much to write, 300 words is a good target. If needed, you can always write more. -See the https://communityblog.fedoraproject.org/writing-community-blog-article/[Writing an article] guide to get started. +See the {COMMBLOG}/writing-community-blog-article/[Writing an article] guide to get started. This page explains the process for writing and how to get your post published. diff --git a/docs/modules/ROOT/pages/contribute/first-steps.adoc b/docs/modules/ROOT/pages/contribute/first-steps.adoc index 597650b..e1ed65a 100644 --- a/docs/modules/ROOT/pages/contribute/first-steps.adoc +++ b/docs/modules/ROOT/pages/contribute/first-steps.adoc @@ -4,19 +4,19 @@ include::{partialsdir}/attributes.adoc[] Are you new to the Fedora community? Not sure where to start? -Learn how to make your first steps in the Fedora community by earning these Fedora Badges. +Learn how to make the first steps in the Fedora community by earning these Fedora Badges. [[fedora-badges]] == What are Fedora Badges? -Fedora Badges are a fun way to earn virtual badges in the Fedora community. +Fedora Badges are a fun way to earn virtual badges for doing helpful things in the Fedora community. There are hundreds of badges to earn for different types of activities. Some badges are for technical tasks while others are for non-technical tasks. To learn more about Fedora Badges, https://badges.fedoraproject.org/about[read the website] for more info. -This page lists some of the best Fedora Badges to earn when you're getting started. -You may be able to earn more badges too! +This page suggests the best Fedora Badges to earn when you are getting started. +You may be able to earn other badges too! But if you aren't sure where to start, begin with these ones. @@ -34,7 +34,7 @@ image::https://badges.fedoraproject.org/pngs/involvement.png[Involvement - Fedor https://badges.fedoraproject.org/badge/white-rabbit[White Rabbit] is awarded when you set your time zone in your Fedora Account System (FAS) account. Some tools in Fedora will display your time zone or what your current local time is. -This is helpful so others know when you may be around or to find good meeting times. +This is helpful so others know when you may be around or not to disturb you. To set your time zone in FAS, follow these steps: . Go to https://admin.fedoraproject.org/accounts/[Fedora Account System] @@ -55,7 +55,7 @@ image::https://badges.fedoraproject.org/pngs/fas-white-rabbit.png[White Rabbit - https://badges.fedoraproject.org/badge/crypto-badger[Crypto Badger] is awarded when you add an SSH key to your Fedora Account System (FAS) account. You may or may not have an SSH key already. -If you do, you can add it to your FAS account with these steps: +If you do, you can add it from a macOS/UNIX/Linux system to your FAS account with these steps: . Generate SSH key using `ssh-keygen` .. If you use defaults, this generates a `~/.ssh/id_rsa` private key file and a `~/.ssh/id_rsa.pub` public key file @@ -68,7 +68,7 @@ If you do, you can add it to your FAS account with these steps: . Select _Save_ The badge is awarded once per week, so you may not get the badge immediately. -If it's longer than seven days, ask for help in irc://irc.freenode.org/#fedora-admin[#fedora-admin] on IRC. +If it is longer than seven days, ask for help in irc://irc.freenode.org/#fedora-admin[#fedora-admin] on IRC. image::https://badges.fedoraproject.org/pngs/fas-crypto-badger.png[Crypto Badger - Fedora Badges] @@ -78,7 +78,7 @@ image::https://badges.fedoraproject.org/pngs/fas-crypto-badger.png[Crypto Badger https://badges.fedoraproject.org/badge/crypto-panda[Crypto Panda] is awarded when you add a GPG public key to your Fedora Account System (FAS) account. You may or may not have a GPG key already. -They are not required. +They are not required to participate. If you want to generate one, read the https://fedoramagazine.org/gnupg-a-fedora-primer/[GPG series] on the Fedora Magazine. If you have a GPG public key, upload it FAS with these steps: diff --git a/docs/modules/ROOT/pages/contribute/join.adoc b/docs/modules/ROOT/pages/contribute/join.adoc index e606192..a331670 100644 --- a/docs/modules/ROOT/pages/contribute/join.adoc +++ b/docs/modules/ROOT/pages/contribute/join.adoc @@ -8,17 +8,16 @@ Become a member of Fedora Community Operations (CommOps) by following these step [[fas]] == Create a FAS account -Create a {FWIKI}Account_System[Fedora Account System account] and sign the {FWIKI}Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement]. -Do this through the {FWIKI}Infrastructure/AccountSystem[Fedora Account System]. +Create a {FWIKI}/Account_System[Fedora Account System account] and sign the {FWIKI}/Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement]. +Do this through the https://admin.fedoraproject.org/accounts/[Fedora Account System]. [[mailing-list]] == Join the mailing list Subscribe to the https://lists.fedoraproject.org/admin/lists/commops.lists.fedoraproject.org[Fedora CommOps mailing list] to receive email discussion by the team. -The mailing list receives low to medium volume. - -The mailing list is a key part to how we communicate. +The mailing list receives low to medium traffic. +The mailing list is a *key part* to how we communicate. News, updates, and discussion are shared through our mailing list. @@ -26,10 +25,10 @@ News, updates, and discussion are shared through our mailing list. == Send a self-introduction Say hello and introduce yourself to the team! -Send a self-introduction to the mailing list and tell us a little about yourself (click mailto:commops@lists.fedoraproject.org[here, Self-Introduction - your name here] to send an intro). +Send a self-introduction to the mailing list and tell us a little about yourself (click mailto:commops@lists.fedoraproject.org[here] to send an intro). Not sure what to say? -Answer some of these questions to get started: +Answer these questions to start: * Why are you interested in contributing to Fedora? * Why are you interested in contributing to CommOps? @@ -42,13 +41,13 @@ Answer some of these questions to get started: [[community-blog]] == Register on Community Blog -The Fedora https://communityblog.fedoraproject.org[Community Blog] is a key component to CommOps. +The Fedora {COMMBLOG}[Community Blog] is a key component to CommOps. An account gives permissions to view article drafts and previews before they are published. If you ever write an article, you will need an account. -To register, log in at the https://communityblog.fedoraproject.org/wp-login.php[login page] with your Fedora Account System (FAS) credentials. +To register, log in at the {COMMBLOG}/wp-login.php[login page] with your Fedora Account System (FAS) credentials. Need more help logging in? -Read the https://communityblog.fedoraproject.org/how-to-log-in/[help page] for more detailed instructions. +Read the {COMMBLOG}/how-to-log-in/[help page] for more detailed instructions. [[irc]] @@ -60,7 +59,12 @@ Our weekly team meetings also take place on IRC. Never used IRC before? See the https://fedoramagazine.org/beginners-guide-irc/[Beginner's Guide to IRC] on the Fedora Magazine. -If you want to stay connected even when you are not online, consider https://opensource.com/article/17/5/introducing-riot-IRC[using Riot] as your IRC client. +Additionally, you can connect temporarily in a chat session in your browser via https://webchat.freenode.net/?channels=fedora-commops[Freenode web chat]. +However, if you want to stay connected even when you are not online, consider https://opensource.com/article/17/5/introducing-riot-IRC[using Riot] as your IRC client. + +For convenience, the IRC channel is bridged to a Telegram group, https://t.me/fedoracommops[@fedoracommops]. +You may also participate via the Telegram group, but you are unable to use or interact with IRC bots (e.g. in meetings). +Join the group at https://t.me/fedoracommops[t.me/fedoracommops]. [[first-steps]] @@ -81,11 +85,11 @@ Look for the https://pagure.io/fedora-commops/issues?status=Open&tags=good+first Does something look interesting? Leave a comment if you have a question or want to work on something. -Also check and see if the ticket has an owner. -If there is no owner, you can take lead on it! -If there is, ask if the owner needs help or if they are still working on the ticket. +Also check and see if the ticket is assigned to someone. +If it is unassigned, you can start working on it now. +If there is an assignee, ask them if they need help or if they are still working on the ticket. -This provides you an opportunity to receive mentorship and get help to start a new task. +This provides an opportunity to receive mentorship and get help to start a new task. [[meetings]] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 413d0ab..c4a15e3 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -7,24 +7,32 @@ image::commops-logo.png[CommOps logo] Community Operations (CommOps) provides tools, resources, and utilities for different sub-projects of Fedora to improve effective communication. The following areas are examples of where CommOps focuses: -* Work closely with https://docs.fedoraproject.org/fedora-project/council/fcaic.html[Fedora Community Action and Impact Coordinator] to prioritize key focus areas -* Assist https://docs.fedoraproject.org/fedora-project/council/fpgm.html[Fedora Program Manager] with release preparations -* Support preparation and execution of Fedora Elections +* Work closely with xref:council::fcaic.adoc[Fedora Community Action and Impact Coordinator] to prioritize key focus areas +* Assist xref:council::fpgm.adoc[Fedora Program Manager] with release preparations +* Support preparation and execution of https://fedoraproject.org/wiki/Elections[Fedora Elections] * Work with sub-projects and teams to improve on-boarding methods and practices * Use metrics and data to improve understanding of Fedora community ** Support development of metrics tooling -* And more (detailed fully below) +* And more (detailed below) [[find-commops]] == Where to find CommOps The CommOps team uses a mailing list and https://en.wikipedia.org/wiki/Internet_Relay_Chat[IRC] channel to communicate. + The mailing list is best for _asynchronous_ communication. +This means it is best for questions or topics that someone may respond to later. +It is better for longer discussions. + The CommOps IRC channel on the https://freenode.net/[Freenode IRC network] is best for _synchronous_ communication. +This means it is best for quick feedback, like in a conversation. +It is helpful for real-time discussions or getting someone's attention. +Additionally, the CommOps IRC channel is bridged to a Telegram group, if Telegram is more convenient. Mailing list:: commops [at] lists [dot] fedoraproject [dot] org (https://lists.fedoraproject.org/admin/lists/commops.lists.fedoraproject.org/[subscribe here]) IRC channel:: irc://irc.freenode.net/#fedora-commops[#fedora-commops] on Freenode +Telegram group:: https://t.me/fedoracommops[@fedoracommops] on Telegram First time using IRC? Look into https://opensource.com/article/17/5/introducing-riot-IRC[Riot], a free and open source client that connects to various IRC networks. @@ -35,8 +43,7 @@ Riot also keeps you connected to IRC even when you're not connected to the Inter == Workflow CommOps uses a ticket-based workflow to keep track of our work. -The repository with tickets is on https://pagure.io/[Pagure]. -The repository is named https://pagure.io/fedora-commops[fedora-commops]. +The repository with tickets is found on https://pagure.io/fedora-commops[pagure.io/fedora-commops]. Tickets are found under the _https://pagure.io/fedora-commops/issues[Issues]_ menu. Various tags are listed at the top of the _Issues_ page. @@ -46,10 +53,10 @@ For good beginner tasks, look at the _https://pagure.io/fedora-commops/issues?st [[meetings]] == Meetings -CommOps holda a meeting once a week on IRC to check in our tasks and plan ahead. +CommOps holds a meeting once a week on IRC to check in on tasks and plan ahead. Check the https://apps.fedoraproject.org/calendar/commops/[CommOps calendar] for the current date and time. -Past meeting minutes are recorded in [https://meetbot.fedoraproject.org/teams/commops/[Meetbot]. +Past meeting minutes are recorded in https://meetbot.fedoraproject.org/teams/commops/[Meetbot]. [[meeting-format]] @@ -73,14 +80,14 @@ CommOps focuses on a few key areas, both technical and non-technical. === Culture The Fedora Project builds and ships a Linux distribution, but there is a community behind the technical work and planning. -In Fedora, we have the https://docs.fedoraproject.org/fedora-project/project/fedora-overview.html#what-is-fedora-all-about[Four Foundations] to represent our community culture. +In Fedora, we have the xref:project::index.adoc#_what_is_fedora_all_about[Four Foundations] to represent our community culture. The Fedora community represents a set of ethics and values to how we build our distribution. These ethics and values create the culture of the Fedora Project. When working in the community, mindfulness of this culture enriches and supports the different sub-communities inside of Fedora. -CommOps builds community infrastructure of support and acceptance for the culture of the Fedora community. +CommOps builds community infrastructure of support and acceptance for the Fedora community's culture. The _Friends_ foundation is there for a reason. -The community infrastructure CommOps assists with, builds on top of the _Friends_ foundation. +The community infrastructure CommOps assists with builds on top of the _Friends_ foundation. People enjoy contributing in a community where they feel valued for who they are and what they bring to the community, not just that they are useful. CommOps supports this through some of our tasks relating to culture. @@ -92,13 +99,13 @@ Examples of things we help with to build and support the culture of the Fedora c === Elections -There are a few elected bodies in Fedora, such as the https://docs.fedoraproject.org/fedora-project/council/charter.html[Fedora Council], https://docs.fedoraproject.org/fedora-project/subprojects/mindshare/mindshare.html[Mindshare Committee], and https://docs.fedoraproject.org/fedora-project/subprojects/fesco/fesco.html[FESCo]. +There are a few elected bodies in Fedora: the xref:project::leadership.adoc[Fedora Council], xref:mindshare::index.adoc[Mindshare Committee], and xref:fesco::index.adoc[FESCo]. Every new Fedora release, the community holds elections for these bodies. -Each election takes "wrangling" work to pull together. +Each election takes "wrangling" work to pull it together. This includes calling for nominations, conducting interviews with candidates, and raising awareness during the voting window. -CommOps supports the https://docs.fedoraproject.org/fedora-project/council/fpgm.html[Fedora Program Manager] in organizing and executing elections. -These responsibilities consist of curating content on the https://docs.fedoraproject.org/fedora-project/subprojects/mindshare/docs/community-blog.html[Community Blog], creating interview templates, and outreach to grow awareness. +CommOps supports the xref:council::fpgm.adoc[Fedora Program Manager] in organizing and executing elections. +These responsibilities consist of curating content on the xref:community-blog.adoc[Community Blog], creating interview templates, and outreach to grow awareness. Examples of things we do to help organize and execute Fedora elections: @@ -110,8 +117,8 @@ Examples of things we do to help organize and execute Fedora elections: === Storytelling -Messaging and storytelling bring the "story" of the Fedora Project to both the contributor and user community. -Every year, a https://mattdm.org/fedora/2018devconf/DevConfcz2018Charts.pdf[couple thousand people] work on Fedora. +Messaging and storytelling bring the Fedora Project "story" to both contributors and user communities. +Every year, a https://mattdm.org/fedora/2018flock/2018-State-of-Fedora.pdf[couple thousand people] work on Fedora. Messaging is a way of sharing our story in multiple formats. We bring the message of what we _as a community_ are doing out to others. Others include our contributors working in other areas of the project and users interested in what the Fedora community produces. @@ -120,7 +127,7 @@ Communicating the story of Fedora keeps our contributors moving together towards Good messaging helps our users better understand the goals and objectives of Fedora and how we plan to get there. CommOps supports messaging by working with other sub-projects and teams to tell their own stories. -CommOps provides the help to "dig out" the stories and the tools to share them widely. +CommOps provides help to "dig out" the stories and tools to share them widely. This includes tasks like interviews, sharing activities by Fedora contributors, running retrospectives, and more. These tasks keep contributors in sync with what we're working on. They are direct actions to keep everyone on the same page. @@ -170,15 +177,18 @@ Examples of sub-project support and on-boarding work: [[join-commops]] == Join CommOps +Read our guide on xref:contribute/join.adoc[how to join the CommOps team]. + CommOps always welcomes new contributors. Whether you are a newcomer or an old-timer, there are ways to get involved. Join CommOps to: -* Build your portfolio working on real-world projects -* Gain holistic view of the Fedora Project and learn how the pieces fit together +* Build your portfolio in open source community management +* Directly see the impact of your contributions over time +* Gain a holistic view of the Fedora Project and learn how the pieces fit together * Work directly with Fedora Project leadership * Work with teammates from around the world -* Aspire to the greatness of a superhero +* Aspire to the greatness of a community superheroine or superhero .Join the CommOps team today [link="contribute/join/"] @@ -189,14 +199,14 @@ image::https://fedoraproject.org/w/uploads/7/72/Happypanda.png[Happy Panda,100] == Toolbox The CommOps toolbox explains tools and services often used by the team. -The tools are organized by their purpose and use. +The tools are organized by purpose and use. [[communication-tools]] === Communication tools -These tools are for communicating to others in the Fedora community. +These are communication tools to share content and information with others in the Fedora community. -https://docs.fedoraproject.org/fedora-project/subprojects/mindshare/docs/community-blog.html[Community Blog] (CommBlog) - https://communityblog.fedoraproject.org/[communityblog.fedoraproject.org]:: +xref:community-blog.adoc[Community Blog] (CommBlog) - https://communityblog.fedoraproject.org/[communityblog.fedoraproject.org]:: Centralized blog for contributors to publish news, activities, or calls for help to the rest of the project. Useful place for getting an inside scoop on "what's happening" in Fedora. @@ -208,7 +218,7 @@ Relays real-time updates and changes relating to CommOps in our IRC channel. [[metrics-tools]] === Metrics tools -These tools access and use the Fedora messaging bus, **fedmsg**. +These tools access and use the Fedora messaging bus, {FEDMSG}[**fedmsg**]. With these tools, you can generate metrics, analyze data, and interact with fedmsg. https://github.com/fedora-infra/fedora-stats-tools/blob/develop/annualgrepper.py[annualgrepper]:: @@ -245,9 +255,6 @@ Measure the ratio of activity per user to approximate burnout https://github.com/fedora-infra/fedora-stats-tools/blob/develop/meetbot-fedmsg-activity.py[meetbot-fedmsg-activity.py]:: Jinja2 template that creates links to Meetbot activities -https://github.com/fedora-infra/statscache[statscache]:: -Daemon to build and keep highly-available fedmsg statistics - https://pagure.io/wordcloudbot[wordcloudbot]:: Create pretty wordclouds from IRC meeting logs From 3eb6caa2acff2384fdcc55f0cc552129cd2962bf Mon Sep 17 00:00:00 2001 From: Justin W. Flory Date: Sep 10 2018 23:48:30 +0000 Subject: [PATCH 2/2] Ignore produced documentation artifacts in gitignore --- diff --git a/.gitignore b/.gitignore index 9f3ebf5..b05253d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,9 @@ +# Documentation artifacts +# Likely related to the Antora toolchain for docs-fp-o +_package/ +_preview/ + +# Misc. build cache public