Add the initial work on the CPE documentation
Signed-off-by: Pierre-Yves Chibon <pingou@pingoured.fr>
This commit is contained in:
parent
7b2d884d0d
commit
89128de26c
9 changed files with 371 additions and 0 deletions
16
antora.yml
Normal file
16
antora.yml
Normal file
|
|
@ -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: cpe # <---- PLEASE MODIFY
|
||||
|
||||
# Title will be visible on the page.
|
||||
title: Community Plateform Engineering # <---- 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: cpe:index
|
||||
|
||||
# This lists all the menu definitions of your component.
|
||||
nav:
|
||||
- modules/cpe/nav.adoc
|
||||
46
build.sh
Executable file
46
build.sh
Executable file
|
|
@ -0,0 +1,46 @@
|
|||
#!/bin/sh
|
||||
|
||||
image="docker.io/antora/antora"
|
||||
cmd="--html-url-extension-style=indexify site.yml"
|
||||
|
||||
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 ""
|
||||
echo "This build script is using Docker container runtime to run the build in an isolated environment."
|
||||
echo ""
|
||||
docker run --rm -it -v $(pwd):/antora $image $cmd
|
||||
|
||||
elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then
|
||||
# Running on Linux.
|
||||
# Check whether podman is available, else faill back to docker
|
||||
# which requires root.
|
||||
|
||||
if [ -f /usr/bin/podman ]; then
|
||||
echo ""
|
||||
echo "This build script is using Podman to run the build in an isolated environment."
|
||||
echo ""
|
||||
podman run --rm -it -v $(pwd):/antora:z $image $cmd
|
||||
|
||||
elif [ -f /usr/bin/docker ]; then
|
||||
echo ""
|
||||
echo "This build script is using Docker to run the build in an isolated environment."
|
||||
echo ""
|
||||
|
||||
if groups | grep -wq "docker"; then
|
||||
docker run --rm -it -v $(pwd):/antora:z $image $cmd
|
||||
else
|
||||
echo ""
|
||||
echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password."
|
||||
echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/."
|
||||
echo ""
|
||||
sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd
|
||||
fi
|
||||
else
|
||||
echo ""
|
||||
echo "Error: Container runtime haven't been found on your system. Fix it by:"
|
||||
echo "$ sudo dnf install podman"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
3
modules/cpe/nav.adoc
Normal file
3
modules/cpe/nav.adoc
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
* xref:mission_statement.adoc[Mission Statement]
|
||||
* xref:working_with_us.adoc[Working With the CPE Team]
|
||||
** xref:initiatives.adoc[Initiatives]
|
||||
43
modules/cpe/pages/index.adoc
Normal file
43
modules/cpe/pages/index.adoc
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
= The Community Plateform Engineering
|
||||
|
||||
In 2017 the Fedora Engineering team merged with the CentOS Engineering team
|
||||
to form what is now called the Community Platform Engineering (CPE) team.
|
||||
For the team members, the day to day work did not change much.
|
||||
|
||||
The members working on Fedora are still fully dedicated to work on the
|
||||
Fedora Project, and those working on CentOS are still fully dedicated to
|
||||
CentOS. On both projects its members are involved in infrastructure, release
|
||||
engineering, and design. However, it brought the two infrastructures and
|
||||
teams closer to each other, allowing for more collaboration between them.
|
||||
|
||||
There are 20 people on this consolidated team. The breakdown looks like this:
|
||||
|
||||
* In Fedora:
|
||||
|
||||
** 3 dedicated system administrators
|
||||
** 5 dedicated developers
|
||||
** 1 doing both development and system administration
|
||||
** 1 doing both release engineering and system administration
|
||||
** 1 person dedicated to Fedora CoreOS
|
||||
** 2 release engineers
|
||||
** 1 person dedicated to documentation
|
||||
** 1 designer
|
||||
|
||||
* In CentOS:
|
||||
** 1 system administrator
|
||||
** 2 doing both development and system administration
|
||||
** 1 dedicated to the build systems
|
||||
|
||||
* There is also one additional person working on projects internal to Red Hat
|
||||
|
||||
As you can see this team is both quite diverse as well as limited. For
|
||||
example, we do not have dedicated database adminstrators or network engineers
|
||||
even though most of our application is one or the other when not both.
|
||||
|
||||
For these reasons we need to be careful on how our limited resources are
|
||||
spent. The team has therefore defined a xref:mission_statement.adoc[Mission
|
||||
Statement] for itself, allowing to focus its work in certain areas.
|
||||
|
||||
We have also written a document explaining xref:working_with_us.adoc[How to
|
||||
work with us] for small and large tasks. Following this document makes it
|
||||
easier for us to help you.
|
||||
114
modules/cpe/pages/initiatives.adoc
Normal file
114
modules/cpe/pages/initiatives.adoc
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
= New Initiative Workflow
|
||||
|
||||
:toc:
|
||||
|
||||
This document documents a proposed workflow to get new initiatives onto the CPE backlog.
|
||||
|
||||
|
||||
== The different steps
|
||||
|
||||
The process to bring something to the attention of the CPE team is composed
|
||||
from different steps:
|
||||
|
||||
* Propose a new initiative; this proposal gives the what and why of the work
|
||||
asked.
|
||||
* Based on the proposal the team then decides if it fits its mission
|
||||
statement and thus if it is worth pursuing, or if it would land on
|
||||
someone else to work on.
|
||||
* The CPE team together with the submitter work on figuring out the best
|
||||
approach to answer the demand.
|
||||
* Based on the estimated amount of work, the initiatives currently in
|
||||
progress, priorities, and return on investment, the CPE team decides
|
||||
whether they can commit to this initiative, and if so a rough timeline
|
||||
for it.
|
||||
|
||||
|
||||
=== Write down a requirement document
|
||||
|
||||
The CPE team has link:https://hackmd.io/@pingou/rJd0HaipV[prepared a template]
|
||||
for you to use to write down your requirement document.
|
||||
|
||||
This document is divided into two parts, the first part is yours to fill.
|
||||
It is basically the what and why of your request:
|
||||
- What do you want the CPE team to work on
|
||||
- Why do you think it is worth for the CPE team to work on it
|
||||
The second part will be filled out later by you and the CPE team once your
|
||||
proposal has been accepted based on its what and why.
|
||||
|
||||
|
||||
=== Proposing a new initiative
|
||||
|
||||
Once you have written down your requirement document, submit it to the CPE
|
||||
team for review.
|
||||
To do this, simply open a ticket on the link:https://pagure.io/cpe/initiatives-proposal[CPE-initiatives issue tracker].
|
||||
|
||||
You will be asked in this ticket a few things:
|
||||
- a link to your requirement document
|
||||
- potential dependencies for this initiative (dependencies on people or
|
||||
other initiatives)
|
||||
- potential deadlines that could impact the initiative
|
||||
|
||||
|
||||
=== First decision point: is this initiative for the CPE team?
|
||||
|
||||
Based on these information the CPE team will decide if this initiative is
|
||||
in the scope of the CPE team (ie: does it fit its [mission statement]()?)
|
||||
but also if there is a clear benefit for the communities the CPE team is
|
||||
involved in.
|
||||
|
||||
If your initiative doesn't fit for the CPE team, it does not mean your
|
||||
challenge is not worth pursuing but the CPE team has limited resources
|
||||
and needs to be careful on how they are spent.
|
||||
|
||||
Every two weeks, the CPE will meet to go over the initiative proposed. At
|
||||
this point, the CPE team will decide on accepting or not your initiative or
|
||||
if needed appoint someone to work with you to polish this document, improve
|
||||
the user-story, discuss with you what is in scope and what is out of scope.
|
||||
|
||||
|
||||
=== Figuring the technical solution
|
||||
|
||||
If your proposal is validate for the CPE team, you will be asked to
|
||||
collaborate with some CPE team representative to figure out the best
|
||||
technical solution to answer the use-case and users stories set in your
|
||||
requirements document.
|
||||
|
||||
This step may involve calling for feedback the communities affected by this
|
||||
change.
|
||||
|
||||
The part II of the requirement document should be kept up to date to
|
||||
reflect the technical solution of choice and possibly the solutions
|
||||
considered with why they were rejected (this could also be stored in a
|
||||
different document linked to).
|
||||
|
||||
|
||||
=== Final decision and prioritization
|
||||
|
||||
Finally, once the two parts of the requirement document have been filled,
|
||||
the CPE team and its stakeholder will be consulted to decide if the
|
||||
initiative is worth doing and what its priority status should be on the
|
||||
backlog of the team.
|
||||
|
||||
If the initiative is approved, the ticket will be closed as accepted and an
|
||||
epic will be created in the link:https://teams.fedoraproject.org/project/pingou-cpe-dev-1/epics[CPE taiga board].
|
||||
It will then be up to the team working on this epic to track their work in
|
||||
taiga or anywhere else, granted they document in the epic where they are
|
||||
tracking it.
|
||||
|
||||
If the initiative is not accepted by the CPE team, the ticket will be
|
||||
closed as rejected with some explanations as to why.
|
||||
|
||||
Every quarter, the CPE team will meet to plan their work for the coming
|
||||
quarter. During this meeting, the team will go over the proposed and
|
||||
accepted initiatives, weight them against each other, prioritize them and
|
||||
pick the ones that will be worked on.
|
||||
|
||||
|
||||
== Conclusions
|
||||
|
||||
This new workflow will be a change from how the CPE team has worked up
|
||||
until now. Its core idea is to maximize the output of the team to the
|
||||
community. We are not able to accept everything and anything and we want to
|
||||
make sure what we accept is properly limited in scoped and time.
|
||||
Hopefully this will allow us to work on more initiative and bring more
|
||||
beneficent changes to our communities.
|
||||
22
modules/cpe/pages/mission_statement.adoc
Normal file
22
modules/cpe/pages/mission_statement.adoc
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
= The CPE's Mission statement
|
||||
|
||||
The Community Platform Engineering Team is responsible for the
|
||||
infrastructure and services that support developing, building, and
|
||||
releasing of Fedora and CentOS platform artifacts and deliverables,
|
||||
including:
|
||||
|
||||
* Hosting, automating, monitoring and maintaining infrastructure components
|
||||
* Service monitoring and lifecycle management of services hosted within our infrastructure
|
||||
* Feature development for infrastructure-related initiatives
|
||||
* Tooling to enable all of the above
|
||||
|
||||
|
||||
== Why a mission statement?
|
||||
|
||||
A mission statement means the team shares a common vision about what our
|
||||
work is or should be. It gives us clear boundaries for our work and it
|
||||
helps us having a critical view on our work (current or coming): “Does this
|
||||
fit our mission statement?”. With this in mind we can focus on bringing more
|
||||
value to the community. In other words, we want to maximize our value and
|
||||
impact in a targeted mission rather than having limited impact on a broad
|
||||
spectrum.
|
||||
89
modules/cpe/pages/working_with_us.adoc
Normal file
89
modules/cpe/pages/working_with_us.adoc
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
= Working with Community Platform Engineering
|
||||
|
||||
|
||||
This document explains how to efficiently work with the CPE teams.
|
||||
Your close attention to this document will help both you and us
|
||||
do the work you are asking us to do.
|
||||
|
||||
== Urgent Issues / Triage of incoming Issues
|
||||
|
||||
|
||||
Weekly a team member will be designated "oncall". You can find this
|
||||
person on IRC by using '.oncall' in any of our various channels.
|
||||
When available, this person:
|
||||
|
||||
1. Accepts urgent work items for the team, for example a important
|
||||
or high SLE service is down or causing issues. A ticket should
|
||||
be filed by the reporter or the oncall to track this work in any case.
|
||||
|
||||
2. Shields other team members from distracting pings and less
|
||||
urgent tickets, deciding when an issue is important enough to
|
||||
interrupt another team member.
|
||||
|
||||
3. Triages incoming tickets for urgent items that need work outside
|
||||
of normal triage process.
|
||||
|
||||
== Normal operations requests
|
||||
|
||||
|
||||
All normal operations requests should be filed as tickets,
|
||||
work items will not be accepted via private emails or IRC unless
|
||||
the oncall person determines them to be urgent.
|
||||
|
||||
== Normal applications requests
|
||||
|
||||
All normal application bugs should be filed in the upstream
|
||||
tracker for that application where possible, unless it's a
|
||||
deployment issue.
|
||||
|
||||
== Larger projects / feature requests
|
||||
|
||||
All asks involving new applications, major deployments, major development work
|
||||
or the like will be asked to follow the xref:initiatives.adoc[New Initiative
|
||||
Workflow]. It will then be scoped and prioritized from there.
|
||||
|
||||
== General ticket considerations
|
||||
|
||||
Please provide as much information as you can in your ticket to avoid
|
||||
back and forth for information. If you know your issue is going to
|
||||
cause a lot of discussion, start a mailing list thread for that.
|
||||
|
||||
Make sure your ticket:
|
||||
|
||||
* explains the problem or issue you are having, with URLs where
|
||||
possible to the services or applications involved.
|
||||
* tells us how important or urgent this is to you.
|
||||
* includes any error messages or output you see.
|
||||
|
||||
It's up to you as ticket filer to follow your ticket, provide information
|
||||
that is asked for and keep us aware of any urgency you may have, do not
|
||||
simply file and forget your ticket.
|
||||
|
||||
If you are unsure where to file a ticket or what information
|
||||
to place in it, please ask the oncall person or mail the team at https://lists.fedoraproject.org/archives/list/infrastructure@lists.fedoraproject.org/
|
||||
|
||||
Your ticket may well take a while to process depending on the work
|
||||
that the team has and how important we think it is. If your ticket
|
||||
is blocking you, make sure you note that in the ticket but keep in
|
||||
mind that we may be working on tickets that are blocking more people.
|
||||
|
||||
== IRC
|
||||
|
||||
|
||||
IRC is a great way to communicate, but please do not ping team members directly.
|
||||
Instead, update your ticket with any new information you have and when the
|
||||
team member(s) working on that issue have time/availability they may contact
|
||||
you on IRC for more interactive debugging/testing.
|
||||
|
||||
== Direct emails
|
||||
|
||||
Email is also a great communication method, but if you mail work items or
|
||||
information to one person directly, they cannot easily hand off the issue,
|
||||
you must wait for them to have time to address the issue (when others could
|
||||
perhaps have already solved it, etc). So, please avoid direct emails and instead
|
||||
update tickets with any information you want to add.
|
||||
|
||||
== RFC 1149
|
||||
|
||||
link:https://tools.ietf.org/html/rfc1149[Pidgeons are too slow] for most work
|
||||
items, instead update tickets. (and thanks for reading this far).
|
||||
18
preview.sh
Executable file
18
preview.sh
Executable file
|
|
@ -0,0 +1,18 @@
|
|||
#!/bin/sh
|
||||
|
||||
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 ""
|
||||
cd ./public
|
||||
python3 -m http.server 8080
|
||||
fi
|
||||
20
site.yml
Normal file
20
site.yml
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
site:
|
||||
title: Local Preview
|
||||
start_page: cpe:cpe:index
|
||||
content:
|
||||
sources:
|
||||
- url: .
|
||||
branches: HEAD
|
||||
ui:
|
||||
bundle:
|
||||
url: https://asamalik.fedorapeople.org/ui-bundle.zip
|
||||
snapshot: true
|
||||
default_layout: with_menu
|
||||
output:
|
||||
clean: true
|
||||
dir: ./public
|
||||
destinations:
|
||||
- provider: archive
|
||||
runtime:
|
||||
pull: true
|
||||
cache_dir: ./cache
|
||||
Loading…
Add table
Add a link
Reference in a new issue