QuantEcon / QuantEcon/qeps

QEP-1 v4: codify the in-document appendix

Open
#37 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
1
Forks
0
Avg merge
2d 5h
Merged PRs (30d)
7

Description

QEP-5 is the second QEP to carry a normative machine-readable appendix — its Code in brief block, bounded by <!-- qep-appendix: code-in-brief --> and <!-- /qep-appendix --> — after QEP-2's co-located yml. Two instances was the agreed trigger for generalising the convention into QEP-1. QuantEcon/cli#50 consumes QEP-5's block by substring extraction, so the convention has a consumer now.

Proposed shape, to be settled on the amendment pull request:

  • an optional, normative block bounded by <!-- qep-appendix: <id> --> and <!-- /qep-appendix -->, extractable as a substring with no markdown parsing;
  • any change inside the block is a substantive amendment and bumps version;
  • the QEP names the tool that consumes the block;
  • everything stays in the one markdown file: a fenced block for data, a GitHub alert for prose;
  • decide whether QEP-2's yml migrates into a fenced block or stays as the one file-form exception. The check in check-labels.mjs assumes the file form today.

This is a substantive amendment to QEP-1 (v3 → v4) and needs a second reader. Lands after the rollout has exercised the block at least once, so the convention is written from use.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read QEP-1, QEP-2, and QEP-5 to compare the existing appendix forms and review check-labels.mjs, which assumes QEP-2's current file form. Follow the rollout using QuantEcon/cli#50, then settle the proposed QEP-1 v4 convention in an amendment pull request with a second reader.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, markdown
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.