Skip to content

PostKit-week-1.md

Latest commit

 

History

History
191 lines (125 loc) · 2.74 KB

PostKit-week-1.md

File metadata and controls

191 lines (125 loc) · 2.74 KB

Week 1 — PostKit API Design

Overview

This week you will design (not build) the API for your assigned PostKit library.

Your goal: create a clear, usable, well-documented API that another student could use without asking you questions.

Spec:

PostKit-libs.md

🎯 Goal

Define:

  • what your package exports
  • inputs and outputs
  • behavior
  • how to use it

📦 Deliverable

Create a README.md that includes:

1. Package Name

2. Purpose (1–2 sentences)

3. Exports (3–7 total)

For each:

  • name
  • inputs
  • output
  • description

4. Example Usage (hypothetical code)

5. Edge Cases

6. Design Notes

  • explain key decisions

⚠️ Constraints

  • Follow the assigned spec
  • You design the API (names, params, signatures)
  • Must be clear, consistent, and TypeScript-friendly

🚫 Not This Week

Do NOT:

  • implement code
  • write tests
  • publish to npm

🧭 Workflow

  1. Read spec
  2. Sketch API
  3. Write README
  4. Open PR
  5. Get reviews
  6. Revise + get approval

🔁 Peer Review & Approval (Required)

You will submit your API via a Pull Request and review two peers.

Step 1 — Create PR

Branch: api-proposal

PR title:

API Proposal — <package-name>

How:

  1. Create branch
  2. Update README
  3. Commit
  4. Open PR (api-proposal → main)

⚠️ Do NOT commit to main

Step 2 — Review Assignments

Review exactly two libraries:

  • If you are N → review N+1 and N+2
  • Wrap: 9→10,1 and 10→1,2

How to review:

  1. Open repo
  2. Pull Requests tab
  3. Open PR
  4. Files changed
  5. Comment on lines
  6. Submit review

Also: request your reviewers on your PR

Step 3 — Required Feedback

Each review must include:

  • 3+ comments
  • 1 suggestion
  • 1 question

Focus on:

  • clarity
  • inputs/outputs
  • usability
  • edge cases

Step 4 — Revise

  • respond to comments
  • update README
  • push changes

Step 5 — Approval

Required:

  • 2 peer approvals
  • instructor approval

Approval means reviewers can use your API without confusion.

⛔ No approval = no Week 2

⏱️ Deadline

Due: Start of Week 3 All PRs must be created and peer reviews completed by this time.

⚠️ Common Mistakes

  • unclear function names
  • vague inputs/outputs
  • missing examples
  • weak reviews ("looks good")

🧪 Definition of Done

  • README complete
  • API matches spec
  • examples are clear
  • PR approved (2 peers + instructor)

💡 Reminder

A good library starts with a clear API.

Make it:

easy to understand, easy to use, ready to build

Resources