help.html

{%extends "base.html"%}
{%block contents%}
 <p>
  This is the "Commitfest app", the website where the PostgreSQL community tracks proposed changes to PostgreSQL. If you're familiar with GitHub, then this website fulfills a similar purpose to the list of Pull Requests (PRs) on GitHub repo. The most important difference is that the Commitfest app is not the "source of truth", instead the PostgreSQL mailinglists are. The "Commitfest app" is simply a tool to help the communtiy keep track of changes proposed on the mailinglist in an organized manner. Below are the most important concepts that you should know about when using the Commitfest app.
 </p>
 <h2>Commitfest</h2>
 <p>
  PostgreSQL development is organized into "Commitfests" (often abbreviated to "CF"). Each Commitfest contains a list of entries called <a href="#patch">patches</a> (similar to PRs, see below for details). The main purpose of Commitfests are to make sure patches that people are interested in are not forgotten about, as well as running CI (aka CFBot) on these patches. Each Commitfest has a period where it is  "Open", in which people can add patches to the Commitfest. This "Open" period is followed by an "In Progress" period, in which the idea is that committers and reviewers focus on reviewing and committing the patches in this "In Progress" Commitfest. At the end of the month a Commitfest gets "Closed" (and stays closed forever). Any not yet committed patches can be moved to the following "Open" Commitfest by their authors, to try again in the next cycle. Having these timebound periods has several benefits:
  <ol>
   <li>It gives a regular cadence of development to people who like to have this.</li>
   <li>It provides a natural age-out mechanism for patches that the submitter has lost interest in.</li>
   <li>It provides an easy way for reviewers/committers to prioritize which patches to review.</li>
  </ol>
  This <b>does not</b> mean that patches are only committed during a Commitfest, nor that people will only respond on the mainlinglist to patches in the "In Progress" Commitfest.
 </p>
 <p>There are 5 Commitfests per year. The first one is "In Progress" in <em>July</em> and starts the nine months feature development cycle of PostgreSQL. The next three are "In Progress" in <em>September</em>, <em>November</em> and <em>January</em>. The last Commitfest of the feature development cycle is "In Progress" in <em>March</em>, and ends a when the feature freeze starts. The exact date of the feature freeze depends on the year, but it's usually in early April.</p>

 <h2>Patches</h2>
 <p>
  A "patch" is a bit of an overloaded term in the PostgreSQL community. Email threads on the mailing list often contain "patch files" as attachments, such a file is often referred to as a "patch". A single email can even contain multiple related "patch files", which are called a "patchset". However, in the context of a Commitfest app a "patch" usually means a "patch entry" in the Commitfest app. Such a "patch entry" is a reference to a mailinglist thread on which change to PostgreSQL has been proposed, by someone sending an email that contain one or more "patch files". The Commitfest app will automatically detect new versions of the patch files and update the "patch entry" accordingly.
 </p>
 <p>
  There are three "Active" categories of patch status:
  <ul>
   <li><b>Waiting on Author:</b> The author needs to make changes based on a review that took place on the mailinglist.</li>
   <li><b>Needs Reviewer:</b> The patch needs guidance or a review.</li>
   <li><b>Ready for Committer:</b> The patch has been reviewed by non-committers and is considered ready to be committed by one of those reviewers. A committer might still decide that more changes are needed.</li>
  </ul>
  And there are four "Closed" categories of patch status for when a patch has
  been resolved, either by being committed or not:
  <ul>
   <li><b>Committed:</b> A committer has applied the patches to the git repo.</li>
   <li><b>Withdrawn:</b> The author has withdrawn the patch from consideration.</li>
   <li><b>Rejected:</b> A committer has decided that either the feature is not desired, or the design of the patch has severe flaws. People should look at the emails on the email thread, for details on why the patch was rejected.</li>
   <li><b>Returned with Feedback:</b> A committer has decided that the patch needs changes, but the author has not responded for long enough that the patch is now considered inactive. The author (or someoene else) is free to re-open again when they address the required changes.</li>
  </ul>
 </p>

 <h2>Drafts</h2>
 <p>
  Appart from the regular Commitfests, there is also a "Drafts" Commitfest that is used to collect patches for new features that are not yet ready for general reviewing. There are various reasons why a patch might not be ready for general reviewing but the author still wants to track it publicly in the "Commitfest app", this is usually due to the combination of one of the following reasons:
  <ul>
   <li>The author has temporarily lost interest, but expects to come back in the future.</li>
   <li>The author does not want to forget about it </li>
   <li>The author wants feedback from a specific subset of people before requesting general feedback</li>
   <li>The author wants to have CI run on the patch, while they are polishing it further</li>
   <li>The author would like to be notified when the patch is in need of a rebase</li>
  </ul>
  Like regular Commitfests, a Draft Commitfest also has an "Open" period and a "Closed" state, but it has no "In Progress" period. The "Open" period for a Draft Commitfest last lasts a year. When the last Commitfest of the development cycle becomes "In Progress", the Draft Commitfest for that PostgreSQL version is closed, and a new one is immediately opened for the next PostgreSQL release.
 </p>
 <p>Another difference between Draft Commitfests and regular Commitfests is that Draft Commitfests don't list resolved patches.</p>
{%endblock%}