Skip to content

Commit a3a7ecd

Browse files
polobopolobo
committed
Add workflow information page to base.html nav bar
Introductory material to understand how the workflow operates and its terminology and concepts in the software development domain compared to generic project managed. Includes a schedule. Also add a reference guide.
1 parent ac45d5e commit a3a7ecd

File tree

6 files changed

+496
-0
lines changed

6 files changed

+496
-0
lines changed

‎media/commitfest/css/commitfest.css

+83
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,86 @@ div.form-group div.controls input.threadpick-input {
9191
.search-bar {
9292
display: inline-block;
9393
}
94+
95+
/* Header styling */
96+
#workflow-transitions-header {
97+
font-size: 20px;
98+
font-weight: bold;
99+
margin-top: 20px;
100+
color: #333;
101+
border-bottom: 2px solid #ddd;
102+
padding-bottom: 5px;
103+
}
104+
105+
/* Table styling */
106+
#workflow-transitions-table {
107+
width: 100%;
108+
max-width: 500px; /* Updated max-width */
109+
border-collapse: collapse;
110+
margin: 20px 0; /* Remove centering */
111+
font-size: 16px;
112+
text-align: left;
113+
}
114+
115+
#workflow-transitions-table th,
116+
#workflow-transitions-table td {
117+
border: 1px solid #ddd;
118+
padding: 8px;
119+
width: 25%; /* Ensure all columns have the same width */
120+
text-align: center; /* Center-align cell labels */
121+
}
122+
123+
#workflow-transitions-table th {
124+
background-color: #f4f4f4;
125+
color: #333;
126+
font-weight: bold;
127+
text-align: center;
128+
}
129+
130+
#workflow-transitions-table tr:nth-child(even) {
131+
background-color: #f9f9f9;
132+
}
133+
134+
#workflow-transitions-table tr:hover {
135+
background-color: #f1f1f1;
136+
}
137+
138+
#workflow-schedule-table {
139+
width: 100%;
140+
max-width: 800px;
141+
border-collapse: collapse;
142+
margin: 20px 0; /* Remove centering */
143+
font-size: 16px;
144+
text-align: left;
145+
}
146+
147+
#workflow-schedule-table th,
148+
#workflow-schedule-table td {
149+
border: 1px solid #ddd;
150+
padding: 8px;
151+
text-align: center; /* Center-align cell labels */
152+
}
153+
154+
#workflow-schedule-table td {
155+
width: 15%; /* First four columns */
156+
}
157+
158+
#workflow-schedule-table td:nth-child(5),
159+
#workflow-schedule-table td:nth-child(6) {
160+
width: 20%; /* Last two columns */
161+
}
162+
163+
#workflow-schedule-table th {
164+
background-color: #f4f4f4;
165+
color: #333;
166+
font-weight: bold;
167+
text-align: center;
168+
}
169+
170+
#workflow-schedule-table tr:nth-child(even) {
171+
background-color: #f9f9f9;
172+
}
173+
174+
#workflow-schedule-table tr:hover {
175+
background-color: #f1f1f1;
176+
}

‎pgcommitfest/commitfest/templates/base.html

+3
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@
3030
<a href="/account/login/?next={{request.path}}">Log in</a>
3131
{%endif%}
3232
</li>
33+
<li class="pull-right active">
34+
<a href="/workflow">Workflow</a>
35+
</li>
3336
{%if header_activity%} <li class="pull-right active"><a href="{{header_activity_link}}">{{header_activity}}</a></li>{%endif%}
3437
</ul>
3538

‎pgcommitfest/commitfest/templates/workflow-reference.html

+166
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
{%extends "base.html"%}
2+
{%block contents%}
3+
<h2>Overview</h2>
4+
<p>
5+
This reference guide provides a quick reference to the key concepts within
6+
the Commitfest Workflow. There is also an <a href="/workflow">overview</a>
7+
of the workflow built from of these concepts.
8+
</p>
9+
<h3>CFBot</h3>
10+
<p>
11+
The CFBot is continuous integration (CI) infrastructure that uses threads
12+
to retrieve patch files, builds and tests them, and posts the results to
13+
the Patch. Only active patches are tested, and only if they are not in
14+
a "Closed" commitfest.
15+
</p>
16+
<h3>Patches</h3>
17+
<h4>Overview</h4>
18+
<p>
19+
Patches are the projects of the workflow and are linked to the mailing list
20+
threads within which are messages containing versioned patch sets. Patches
21+
are classified as being either active or inactive. They also record
22+
contributors and their roles.
23+
</p>
24+
<h4>Authors, Reviewers, and Committers</h4>
25+
<p>
26+
Especially in open source projects, attribution for work is important. Git
27+
commit messages include author and reviewer attributions (among others) and
28+
inherently identify the committer. To aid the committer in properly recording
29+
attributions in the commit message record authors and reviewers on the patch.
30+
</p>
31+
<p>
32+
Additionally, the commitfest application uses this information to provide
33+
user-specific reporting and notifications.
34+
</p>
35+
<h4>Active</h4>
36+
<p>
37+
A Patch is active if it is in one of the following states:
38+
<ul>
39+
<li>Waiting on Author (Author)</li>
40+
<li>Review Needed (Reviewer)</li>
41+
<li>Ready for Committer (Committer)</li>
42+
</ul>
43+
These correspond to the three people-related fields of the patch and indicate
44+
whose effort is presently needed. Of course, a patch may be in a state for
45+
which no person is assigned; in which case the patch is advertising itself as
46+
needing that kind of attention.
47+
</p>
48+
<h4>Inactive</h4>
49+
<p>
50+
A Patch is inactive if it is in one of the following states:
51+
<ul>
52+
<li>Committed</li>
53+
<li>Withdrawn</li>
54+
<li>Rejected</li>
55+
<li>Returned With Feedback*</li>
56+
</ul>
57+
</p>
58+
<p>
59+
A Committed patch is one whose files have been committed to the repository.
60+
A Withdrawn patch is one where the author(s) have decided to no longer pursue
61+
working on the patch and have proactively communicated that intent through
62+
updating the patch to this state.
63+
</p>
64+
<p>
65+
A Withdrawn patch is the desired outcome if a patch is not going to be committed.
66+
Only an author can withdraw a patch. If the patch simply needs work it should
67+
updated to author and placed into whichever commitfest bin is appropriate.
68+
</p>
69+
<p>
70+
A Rejected patch has the same effect as Withdrawn but communicates that the
71+
community, not the author, made the status change. This should only be used
72+
when it is when the author is unable or unwilling to withdraw the patch or park
73+
it for rework.
74+
</p>
75+
<p>
76+
*Returned With Feedback complements rejected in that the implication of rejected
77+
is that the feature the patch introduces is unwanted while, here, the implementation
78+
is simply not acceptable. The workflow takes a different approach and considers
79+
both to be less desirable than withdraw. Considering the distinction between
80+
author and committer making the decision to be the key difference the workflow
81+
leaves reject as the fallback non-commit option and makes returned a deprecated
82+
administrator-only option.
83+
</p>
84+
<h4>Threads, Messages, and Patch Sets</h4>
85+
<p>
86+
One or more email threads are related to a patch and found within the messages
87+
on these threads are patch sets containing the actual files. The workflow
88+
tracks the metadata for the files within the patch set while the CFBot
89+
uses the metadata to determine which files to retrieve and apply for its tests.
90+
</p>
91+
<h3>Commitfests</h3>
92+
<h4>Overview</h4>
93+
<p>
94+
Commitfests are just a collection of patches. The workflow described above
95+
explains the purpose of these collections and defines which patches belong in
96+
in which collection. One key constraint the described workflow imposes is that
97+
among the statuses listed below at most one commitfest can be in each of them
98+
at any given time (except for "Closed"). This allows for implementing movement
99+
of a patch to be keyed to commitfest status type without the need for further
100+
disambiguation.
101+
</p>
102+
<h4>In Progress</h4>
103+
<p>
104+
An Active (see Workflow above) period where no new features should be added
105+
and the goal is to get as many review"patches committed as possible.
106+
</p>
107+
<h4>Open</h4>
108+
<p>
109+
Patches ready for final review and commit, according to the author, are placed
110+
in the current open commitfest. Upon the scheduled start date it is manually
111+
updated to be an in progress commitfest, at which point no new patches should be
112+
added.
113+
</p>
114+
<h4>Future</h4>
115+
<p>
116+
The PostgreSQL project works on a schedule release cycle. At the beginning
117+
of each cycle the planned commitfest periods are decided and communicated to
118+
the community via the creation of future commitfests. While classified as
119+
future these commitfests are not permitted to associated with any patches.
120+
Their classification is changed to open as each prior in progress commitfest
121+
closes.
122+
</p>
123+
<h4>Drafts</h4>
124+
<p>
125+
The commitfest setup as drafts is used to hold patches that are not intended
126+
to be formally reviewed and committed. Another term is "work-in-progress" (WIP).
127+
Within the Workflow, at the start of the PG18 feature freeze, the existing
128+
"Draft PG18" commitfest is closed and a new "Draft PG19" commitfest is created.
129+
This allows for a fresh start coinciding with the project release cycle.
130+
And while commits cannot accumulate within a drafts commitfest, withdrawn and
131+
rejected patches would and so having a truly never-closing commitfest is not
132+
ideal. Similarly, given the volume of patches, getting rid of abandonment
133+
is counter-productive. This workflow provides a middle-ground between
134+
every-other-month and never patch moving requirements.
135+
</p>
136+
<h4>Closed</h4>
137+
<p>
138+
Drafts and in progress commitfests are closed (open ones
139+
always go through in progress) when the period they cover has passed.
140+
Closing a commitfest does not impact its related patches; though no new
141+
patches can be created for a closed commitfest.
142+
</p>
143+
<h3>Special Patch Situations</h3>
144+
<h4>Moved</h4>
145+
<p>
146+
Patches retain a memory of which commitfests they have been in. When relocated
147+
from one commitfest to another the association with the old commitfest is
148+
marked as being "Moved". This is a special status that is neither active nor
149+
inactive.
150+
</p>
151+
<h4>Is Ignored</h4>
152+
<p>
153+
This check returns true if the patch is active but exists in a closed commitfest.
154+
Conceptually, this is the same as withdrawn, but through inaction.
155+
</p>
156+
<h3>History</h3>
157+
<p>
158+
Textual event log for a patch.
159+
</p>
160+
<h3>Administrative Actions (Admin)</h3>
161+
<p>
162+
Protections put in place to guide the described workflow can be bypassed
163+
by those with the appropriate permissions. Exercising these elevated
164+
permissions is called an administrative action, or administratively performed.
165+
</p>
166+
{%endblock%}

0 commit comments

Comments
 (0)