Skip to content

Prefect PINs - Prefect Improvement Notices⚓︎

Overview⚓︎

PINs (Prefect Improvement Notices) are Prefect’s approach to memorializing important architectural and design decisions. They provide a structured way to document significant changes to the Prefect workflow orchestration platform.

Source: https://github.com/PrefectHQ/prefect (community documentation references) Type: Project-specific decision documentation similar to Python’s PEPs or Rust’s RFCs

What Are PINs?⚓︎

According to Prefect’s community documentation:

“Important architectural and design decisions are memorialized in Prefect Improvement Notices (PINs)”

PINs serve as the official record of:

  • Architectural decisions
  • Design choices
  • Feature proposals
  • Breaking changes
  • Process improvements

Notable PINs⚓︎

Based on the Prefect GitHub repository:

PIN-01: Introduce PINs⚓︎

The foundational PIN that introduced the PIN concept itself, establishing the framework for documenting future decisions.

PIN-04: Result Handling⚓︎

A proposal for consolidating result handling logic in the Prefect workflow system.

PIN-08: Listener Flows⚓︎

A proposal to enable starting a Flow based on events from user-provided sources by leveraging existing Schedule features. (Later superseded)

PIN-15: Skip as Finished + Control Flow Conditional⚓︎

Proposes interpreting Skip states as Finished instead of Successful while introducing more conditional control flow constructs.

PIN on Flexible Schedules⚓︎

Addresses business-day calendars and complex scheduling needs beyond simple cron expressions.

PIN on Prefect CLI⚓︎

Proposes a command-line interface for Prefect, defining the CLI’s structure and capabilities.

PIN on Extension Objects⚓︎

Introduces wrapper objects to extend functionality without changing core APIs, enabling backward-compatible enhancements.

PIN on Obfuscating Data⚓︎

Addresses privacy and data protection for Prefect Cloud users, proposing mechanisms to protect sensitive information.

PIN Characteristics⚓︎

Purpose⚓︎

PINs document decisions that:

  • Have significant architectural impact
  • Affect the user-facing API
  • Introduce breaking changes
  • Establish new patterns or conventions
  • Require community input and consensus

Lifecycle⚓︎

Based on repository patterns:

  1. Proposal: Created as GitHub issue or pull request
  2. Discussion: Community and maintainers provide feedback
  3. Revision: Updated based on feedback
  4. Decision: Accepted or rejected by maintainers
  5. Implementation: If accepted, implemented in code
  6. Documentation: Becomes permanent record

Status Tracking⚓︎

PINs appear to use GitHub’s issue/PR system for status:

  • Open: Under discussion
  • Closed (Merged): Accepted and implemented
  • Closed (Not Merged): Rejected
  • Superseded: Replaced by later PIN

Relationship to Other Processes⚓︎

Similar To⚓︎

  • Python PEPs (Enhancement Proposals): Structured improvement proposals
  • Rust RFCs (Request for Comments): Community-driven design documents
  • Ethereum EIPs: Standards and improvement proposals

Different From⚓︎

  • ADRs: PINs are forward-looking proposals, while ADRs document decisions already made
  • Issue Tracking: PINs are specifically for architectural/design decisions, not bugs or features
  • Documentation: PINs focus on why and how, not just what

Integration with Development⚓︎

GitHub-Centric⚓︎

PINs leverage GitHub’s features:

  • Issues: For initial discussion and proposal
  • Pull Requests: For detailed technical proposals with code examples
  • Comments: For community feedback and iteration
  • Labels: For categorization and tracking
  • Milestones: For version planning

Community Input⚓︎

PINs enable:

  • Open discussion before implementation
  • Transparency in decision making
  • Community feedback and alternatives
  • Documentation of rationale
  • Historical context for future maintainers

Documentation Challenges⚓︎

Based on GitHub issues:

  • Issue #930: “Links to individual PINs are broken in docs”
    • Indicates there were some challenges maintaining PIN documentation
    • Suggests PINs may have been moved or reorganized

This highlights a common challenge with any documentation system: maintaining links and accessibility over time.

Benefits of the PIN Approach⚓︎

For the Project⚓︎

  • Structured decision making: Consistent process for major changes
  • Community engagement: Users can participate in design
  • Historical record: Understanding why decisions were made
  • Transparency: Open development process

For Contributors⚓︎

  • Clear process: Knows how to propose changes
  • Visibility: Can see what’s being considered
  • Feedback mechanism: Can influence direction
  • Learning: Understand design philosophy

For Users⚓︎

  • Advance notice: See upcoming changes
  • Provide input: Influence features that affect them
  • Understanding: Learn why things work the way they do
  • Trust: Transparent, reasoned decision making

Comparison to Traditional ADRs⚓︎

Similarities⚓︎

  • Document important decisions
  • Capture context and rationale
  • Create permanent record
  • Support future understanding

Differences⚓︎

Aspect PINs Traditional ADRs
Timing Before implementation (proposals) After decision (records)
Audience Community + maintainers Internal team
Process Public discussion Team consensus
Platform GitHub issues/PRs Markdown in repo
Mutability Can be revised during discussion Immutable once accepted
Scope Major features/changes Any architectural decision

Use Cases for PIN-style Approach⚓︎

Best For⚓︎

  • Open source projects: Community involvement needed
  • Breaking changes: Need to communicate and justify
  • API design: User-facing decisions need input
  • Platform changes: Significant architectural shifts
  • Standard setting: Establishing conventions

Consider Traditional ADRs Instead When⚓︎

  • Internal decisions: No external stakeholders
  • Non-controversial: Team consensus already exists
  • Implementation details: Not user-facing
  • Rapid iteration: Too much process overhead
  • Smaller scope: Doesn’t warrant public discussion

Implementation Considerations⚓︎

Starting a PIN Process⚓︎

  1. Define scope: What types of decisions warrant a PIN?
  2. Create template: Structure for proposals
  3. Establish process: Workflow from proposal to decision
  4. Document guidelines: Help contributors understand
  5. Track decisions: Maintain index of PINs

Maintaining PINs⚓︎

  • Version control: Store in git repository
  • Indexing: Maintain searchable list
  • Linking: Connect to related issues and PRs
  • Archiving: Keep historical PINs accessible
  • Updating: Mark superseded PINs clearly

Key Takeaways⚓︎

  1. PINs are proposals, not records: Forward-looking rather than historical
  2. Community engagement: Open source projects benefit from transparent discussion
  3. GitHub integration: Leverages existing tools rather than new systems
  4. Flexible process: Adapts to project needs
  5. Documentation challenges: Requires maintenance and organization

Use Cases⚓︎

  • Best for: Open source projects with community stakeholders
  • Project Size: Medium to large open source projects
  • Team Size: Distributed teams with external contributors
  • Culture: Open, collaborative development
  • Formality: Semi-formal to formal
  • Visibility: Public, transparent decision making