What is a PIP?

[Note: This is work-in-progress for a proposal heavily inspired by similar mechanisms from other communities (see Related) and adapted to the needs of the Prolog language community.]

[Note: If you have comments please post them at the Prolog Community Discourse for this PIP]

A PIP (Prolog Improvement Proposal) is a design document providing information to the Prolog community about the design and implementation of new developments related to the Prolog language, such as new features or libraries.

Purpose

The purpose of this PIPs collection is to act as a indexed repository of language and system-specific proposals that may be of interests for the Prolog community, and to document interesting information regarding their benefits, inconveniences, support status, etc. PIPs also can serve as a link between systems, papers, implementors, researchers, and advanced users.

The purpose of a PIP and the responsibilities of its authors are:

Provide concise information about the rationale of the proposal and guidelines (including pointers to papers, documentation, discussions, reference implementations, or other documents, etc.).
Collect community input (both positive and negative) on particular issues.
Help distill, compare, evaluate, and share proposals. Encourage both new ideas as well as literature research.
When possible, collaborate with formal standardization processes and in particular the Prolog ISO standard. This may cover changes to the ISO Prolog standard (for which there may not be consensus for standardization yet), implementation-specific details for some particular system, helping identify and commenting on non-conformant proposals, or marking proposals as candidates for future ISO extensions.

PIP Types

We consider the following types of PIPs:

meta: A PIP about the PIP repository, workflow, and governance (like this document).
feature: Describes a new language feature (which is typically implemented in the compiler or engine, and cannot be implemented by the majority of systems as a library).
library: Features that can be implemented as libraries.

PIP Workflow

A PIP is a text document (formatted in markdown) that must include a header with metadata about the proposal followed by the body of the proposal.

PIP Header

---
PIP: <PIP id>
Title: <Title>
Author: <authors>
Promoter: <authors or system promoting this PIP>
Discussions-To: <URL for discussion thread>
Status: <draft | abandoned | rejected | withdrawn | accepted | supported | superseded | replaced>
Supported: <system-ids that support it>
Type: <meta | feature | library>
Content-Type: text/markdown
Requires: <PIP numbers>
Conflicts: <PIP numbers>
Created: <date>
Replaces: <PIP number>
Superseded-By: <PIP number>
---

PIP Body

This is a suggestion for the PIP body:

# Abstract

# Motivation and Rationale

# Main section(s)

Describe the proposal, design impact, alternatives, related work. If needed clearly specify out-of-scope ideas.

# Implementation

Details for implementation. This may point to external documents or reference implementations.

The copyright of the PIP is expected to be public domain. We encourage including an Acknowledgements section.

PIP Workflow and Lifecycle

Creation

The process to include a PIP in this repository is the following:

Submit your PIP proposal at the discourse site: create a new topic with a descriptive title.

Alternatively:

Fork the PIPs repository.
Create a new markdown file with a descriptive name (e.g., 0000-new-feature.md). Keep 0000 as PIP id for now. PIP may contain additional files under the 0000-new-feature/ directory.
Submit your PIP via pull request (PR in GitHub) or merge request (MR in GitLab). Indicate whether you or another person is willing to act as a “custodian” to accompany the lifecycle of the PIP.
A lightweight review will check that the proposal satisfies the requirements (like some evidence for support from a few Prolog systems), and assign you a PIP number. Rename your file(s) and update the PR/MR (e.g., 1234-new-feature.md, 1234-new-feature/).

Lifecycle

Each PIP will start with a draft status and evolve as follows:

draft -> candidate: as a precondition for this transition, the PIP’s custodian and a supporter must agree that the PIP’s specification is sufficiently precise and mature. The candidate PIP should enable other implementors to implement the PIP independently. A majority of systems agree on the idea or consider that the inconveniences have been properly identified. One working implementation or prototype must already exist. If appropriate, a test suite should be attached to the PIP.
candidate -> accepted: the proposal has been implemented in at least one system different from the original (use the PIP header to document it). The PIP’s custodian proposes to go ahead. A majority of systems accept and support the PIP. Supporting the proposal does not commit systems to implement them.
draft/candidate -> reject/withdraw: after discussions the author decides to withdraw, or a majority agrees to reject the proposal (objective rationale for it should be documented)
accepted -> superseded: used to annotate that a previously accepted PIP has been superseded or replaced by another (fill the appropriate header field too)

PIP Reviewers and Repository Moderators

(TBD) People responsible for reviewing changes and moderate updates in the repository.