GSoD 2019
This page is for collecting ideas for future Season of Docs projects.
Regarding Project Ideas
Project ideas are to be added here by community members.
Mentors (2019)
The following individuals have been listed as possible mentors on the below projects, and/or offered to be mentors for technical writer-proposed projects:
Organization Administrators
- Stephen Frost
- Sarah Conway
PostgreSQL
- James Chanco
- Alan Youngblood
- Pavan Agrawal
- Evan Macbeth
- Amit Kumar Jaiswal
- Lætitia Avrot
- Tahir Ramzan
- Jeremy Schneider
- Darren Douglas
- Peter Eisentraut
pg_partman
- Keith Fiske
pgJDBC
- Dave Cramer
PL/R
- Dave Cramer
PostGIS
- Martin Davis
- Regina Obe
pgBackRest
- David Steele
- Cynthia Shang
Documentation Project Ideas
General Changes
Suggested by Oleg Bartunov.
Currently, our documentation follows the format of primarily being in a reference manual format. This should be updated, section-by-section, to be more of a user manual format. This should be supplemented by architectural diagrams and visual references, which would need to be created.
Introductory Resources
Suggested by Oleg Bartunov.
We currently don't have a community resource available that's suitable for absolute beginners for PostgreSQL. We want to ensure that new users of PostgreSQL have a positive experience from the start, and this begins with proper documentation that is simple and approachable. Existing external resources could be adapted for this purpose, including the following that was suggested by Oleg:
https://edu.postgrespro.ru/introbook_v4_en.pdf
Introductory Tutorial
Suggested by Pavan Agrawal, James Chanco.
The introductory tutorial available (https://www.postgresql.org/docs/current/tutorial-install.html) in the documentation is not ideal for absolute beginners or those new to databases. It's extremely jargon-heavy and not beginner friendly. This should either be updated or expanded to better suit this purpose.
Additionally, there are several sections in the tutorial where prior knowledge is assumed, such as how to connect to psql. These sections are currently unclear, and should be rewritten for clarity and accuracy.
The original task from Google Code-in 2018:
The PostgreSQL documentation has a set of existing tutorials, one of which is "Getting Started". Attempt to follow this tutorial to install PostgreSQL, create a PostgreSQL database and then access that database. Make notes of issues trying to follow the tutorial, areas where the tutorial lacks specific information to be able to accomplish the task, places where the tutorial doesn't provide information about how to tell if a given step was successful or not, and other items which could be improved.
Using these notes, make changes to the PostgreSQL tutorial in its source format to address the deficiencies and submit these changes as patches to the PostgreSQL source tree so that they can be included in PostgreSQL in the future. These changes must be able to be patched to the PostgreSQL source code and the resulting changes built using the PostgreSQL build tool-chain.
Document the patch submitting process
PostgreSQL development revolves around CommitFest periods, but the process of submitting patches is tedious.
The documented steps for submitting and reviewing a patch need to be reviewed, and the documentation expanded with useful details and links.
More information about patch submission and review: https://wiki.postgresql.org/wiki/Reviewing_a_Patch
Document the Extension submitting process
PostgreSQL Database is known to be very extensible. Currently the Extension documentation is sparse:
https://www.postgresql.org/docs/devel/static/external-extensions.html
The task is to extend this page with more information about developing extensions, add useful resources, and pointers to the Extension Network (PGXN).
Compose cheat sheets for common tools/operations in PostgreSQL
Compose various cheat sheets for common tools/operations in PostgreSQL like Julia Evans did for Linux commands (https://jvns.ca/blog/2017/12/27/a-perf-cheat-sheet/).
Installing Managing clusters Basic settings Controlling a PostgreSQL server(start, stop, restart...) Security checks Performances checks Upgrading psql tool pg_dump tool pg_restore tool
Upgrade pg_backrest tutorial with Postgres 11
The pgbackrest tutorial was written for postgres 9.4 (https://pgbackrest.org/user-guide.html). Maybe it's time to upgrade it to postgres 11.
Step needed:
Understand the user guide Test it with a postgres 11 version Upgrade the tutorial for postgres 11
Compose a cheat sheet for backing up and restoring a PostgreSQL instance using X backup tool (11 tasks)
The purpose of this task is to guide a user about how to backup and restore using different tools with their pros and cons. Each tool is equal to one task:
Amanda: http://www.amanda.org/
Bacula: https://www.bacula.org/
Backup and Recovery Manager for PostgreSQL: https://www.2ndquadrant.com/
Barman https://www.pgbarman.org/
Handy Backup: https://www.handybackup.net/
Iperius Backup: https://www.iperiusbackup.com/
NetVault Backup: https://www.quest.com/products/netvault-backup/
pgBackRest: https://pgbackrest.org/
PostgreSQL backups: https://www.pgbarman.org/
Simpana: https://www.commvault.com/
Spectrum Protect: https://www.ibm.com/us-en/marketplace/data-protection-and-recovery
Manuals: https://severalnines.com/blog/top-backup-tools-postgresql
Write a PostgreSQL technical mumbo-jumbo dictionary
The main goal of this task is to create a HTML website/page to explain some technical words used either in the database world or specifically in Postgres world. Examples of words you could find in that dictionary :
- cluster
- vacuum
- WAL
- query
Document how to migrate a trigger-based partitioned table to a natively partitioned table (pg_partman)
PostgreSQL 10 introduced native partitioning, but previous versions had a method of partitioning that used a combination of triggers, constraints & inheritance.
https://www.postgresql.org/docs/9.6/static/ddl-partitioning.html
Document a method that can be used to migrate to the new native partitioning scheme with minimal downtime to the end users of that table.
https://www.postgresql.org/docs/10/static/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE
The main objective of this task is to provide the working example. If there is any difficulty working out the commands or methods to do this, those answers can be provided. Documentation should be provide in markdown format.
https://github.com/pgpartman/pg_partman
Document a working example of how to migrate a table to native partitioning in PG11 with minimal downtime (pg_partman)
The new DEFAULT partition feature in PG11 should make migrating an existing table to a natively partitioned one a lot easier. However, a new child table with constraints that would match data that exists in that DEFAULT table are not allowed to be added. Using PostgreSQL's transaction system, document a method to move the data and attached a child table with minimal downtime to users of the table in question.
The main objective of this task is to provide the working example. If there is any difficulty working out the commands or methods to do this, those answers can be provided. Documentation should be provide in markdown format.
https://github.com/pgpartman/pg_partman
Review and improve the documentation for PG Partition Manager (pg_partman)
The pg_partman documentation has grown quite extensive over the years since it was released. Looking for a basic review of the top level README and files contained in the docs folder for grammar and clarity. Any other recommendations to improve documentation are welcome as well.
Using Github, fork the repository and submit documentation improvements back via a pull request.
https://github.com/pgpartman/pg_partman
Add documentation for JDBC driver CopyManager API (pgJDBC)
The PostgreSQL JDBC driver, pgjdbc, supports COPY commands to both STDIN and STDOUT via a non-JDBC extension, the CopyManager interface. While the driver has supported this functionality for many years, it's not documented in the official docs.
The purpose of this task is to add some basic documentation of how to use the CopyManager interface to the official pgjdbc docs. The test suite for the pgjdbc driver includes examples of how to use the CopyManager interface and would a good resource for real world usage.
The expected submission for this task will be a pull request on the pgjdbc GitHub page, https://github.com/pgjdbc/pgjdbc, for the documentation patch.
Add tutorial on logical Replication to PostgreSQL Documentation
The PostgreSQL documentation has a section for tutorials, but lacks a tutorial which covers logical replication between PostgreSQL systems.
The tutorial should be in the same format as the PostgreSQL documentation and should be submitted as a patch to the PostgreSQL source code and successfully built using the PostgreSQL build tool-chain. The simplest approach to writing this documentation is to pull down the PostgreSQL source code, build all of PostgreSQL, including the documentation, then work with PostgreSQL to set up logical replication following the existing documentation and ultimately make a copy of an existing tutorial section and then rewrite it to be the logical replication tutorial.
Add tutorial on physical Replication to PostgreSQL Documentation
The PostgreSQL documentation has a section for tutorials, but lacks a tutorial which covers physical replication between instances.
The tutorial should be in the same format as the PostgreSQL documentation and should be submitted as a patch to the PostgreSQL source code and successfully built using the PostgreSQL build tool-chain. The simplest approach to writing this documentation is to pull down the PostgreSQL source code, build all of PostgreSQL, including the documentation, then work with PostgreSQL to set up physical replication following the existing documentation and ultimately make a copy of an existing tutorial section and then rewrite it to be the physical replication tutorial.
Add tutorial on partitioning to PostgreSQL Documentation
The PostgreSQL documentation has a section for tutorials, but lacks a tutorial which covers partitioning of a PostgreSQL table.
The tutorial should be in the same format as the PostgreSQL documentation and should be submitted as a patch to the PostgreSQL source code and successfully built using the PostgreSQL build tool-chain. The simplest approach to writing this documentation is to pull down the PostgreSQL source code, build all of PostgreSQL, including the documentation, then work with PostgreSQL to set up partitioning following the existing documentation and ultimately make a copy of an existing tutorial section and then rewrite it to be the partitioning tutorial.
Review and improve the "Advanced Features" tutorial in the PostgreSQL Documentation
The PostgreSQL documentation has a set of existing tutorials, one of which is "Advanced Features". Attempt to follow this tutorial, after installing PostgreSQL and creating a database and learning some SQL, to work with some of the Advanced Features of PostgreSQL including creating views, foreign keys, transactions, window functions, and inheritance. Make notes of issues trying to follow the tutorial, areas where the tutorial lacks specific information to be able to accomplish the task, places where the tutorial doesn't provide information about how to tell if a given step was successful or not, and other items which could be improved.
Using these notes, make changes to the PostgreSQL tutorial in its source format to address the deficiencies and submit these changes as patches to the PostgreSQL source tree so that they can be included in PostgreSQL in the future. These changes must be able to be patched to the PostgreSQL source code and the resulting changes built using the PostgreSQL build tool-chain.
Review and improve the "SQL Language" tutorial in the PostgreSQL Documentation
The PostgreSQL documentation has a set of existing tutorials, one of which is "SQL Language". Attempt to follow this tutorial, after installing PostgreSQL and creating a database, to use and learn SQL with PostgreSQL. Make notes of issues trying to follow the tutorial, areas where the tutorial lacks specific information to be able to accomplish the task, places where the tutorial doesn't provide information about how to tell if a given step was successful or not, and other items which could be improved.
Using these notes, make changes to the PostgreSQL tutorial in its source format to address the deficiencies and submit these changes as patches to the PostgreSQL source tree so that they can be included in PostgreSQL in the future. These changes must be able to be patched to the PostgreSQL source code and the resulting changes built using the PostgreSQL build tool-chain.
Improve VACUUM Progress Reporting documentation
Suggested by Jeremy Schneider and Jim Nasby
The docs on VACUUM Progress Reporting list the phases of vacuum, but they don't mention that some of these phases can be repeated - and why those phases would be repeated, and what factors (config settings, attributes of data, num_dead_tuples/max_dead_tuples) influence this behavior. These topics are important for people administrating PostgreSQL.
Should discuss in what order PostgreSQL chooses tables to vacuum - and would be good to at least mention what an "aggressive" vacuum is and what it looks like (I need to check if this is covered elsewhere), and discuss block skipping/freeze map/visibility map as they relate to vacuum.
Need to determine what information goes in the main vacuum documentation and what goes in the pg_stat_progress_vacuum docs, staying in line with existing conventions for how docs are organized.
Add more images
Suggested by Peter Eisentraut
As of PostgreSQL 12, the PostgreSQL documentation can contain images. Right now, we have the total of two images. Find places where images would be sensible and add them. This wouldn't necessarily require great artistry, only a sense of where some artistry would be useful.
"SQLite has a bubble generator tool that they use to generate syntax diagrams for their documentation" https://www.postgresql.org/message-id/flat/20190328222500.GA16520%40alvherre.pgsql#c1c100db6b90697674e6fa88573bc9a5
Suggested by Peter Eisentraut
Some people have difficulty finding things on the web site. For example, there are too many top-level categories. Are mailing lists under "Community", "Developers", or "Support"? Find a more sensible and easier hierarchy. Note: The design of the web site would not be part of this project, only the hierarchy and relationship of the pages.
FAQ for pgBackRest
Suggested by Cynthia
This project will be to review the issues log for all issues marked as questions to identify repeat questions. From this, an FAQ will be developed as well as identifying any areas in the documentation that may already address the subject but are insufficient in clarity.
Clean up Authentication Methods
Suggested by Renee
This section of the documentation is .... a bit circular. Perhaps someone could clean it up in Season of Docs (and probably review the rest of the security section for clarity and usefulness)
https://www.postgresql.org/docs/10/auth-methods.html#AUTH-BSD
PostGIS Projects
Managed by Martin Davis
