Versioning policy and numbered deprecations before 1.0.0

Aberta
#491 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
35/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
javascript

Direção de pesquisa

Start with PRODUCT.md, then inspect the versioning, upgrading, contribution, and agent guidance documents named in the issue, along with open issue #478. The issue defines the policy but leaves substantial research and implementation across documentation, deprecation tooling, tests, and package release processes. Done means the policy, numbered deprecation workflow and register, guidance, and pre-1.0 breaking change review are complete; first check how Node.js, Kubernetes, and Angular handle deprecations.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

documentation

Before pivotkit goes to 1.0.0, I want a written versioning policy and the means to keep it. The goal: someone who merges minor and patch releases automatically never gets a break without warning.

Policy (decided)

  • Semantic Versioning, strictly, from 1.0.0. Patch: fixes only. Minor: additions; what is to go away is only deprecated. Major: the only place where deprecated things are removed.
  • One documented exception: a security fix may close an unsafe default in a minor or patch release, marked "Security" in the release notes, with detection and a way back.
  • 0.x stays as it is: under active development, a minor can break, and every break is listed on the upgrading page. We still break as little as possible.
  • All packages start 1.0.0 together.

Work

  • docs/versioning.md: the policy and the list of what counts as public interface (view file format, JS exports, REST/OpenAPI, MCP tool names and schemas, CLI flags, config keys, environment variables, error codes) and what does not (look and CSS details, message wording, internal modules, xlsx layout beyond the values).
  • Numbered deprecations: each gets an id PK-DEP-NNNN, a runtime warning, a check-config line, an entry on the upgrading page with the replacement, and a register in the docs. Removal no earlier than the next major.
  • Where possible, old input keeps working (translated to the new form) until the major.
  • CONTRIBUTING.md and AGENTS.md: how to deprecate (code, test, register, upgrading page).
  • Check open issues for pending breaking changes before 1.0.0 (for example #478).
  • Verify how comparable projects do it (Node.js DEP codes, Kubernetes and Angular deprecation policies) and adopt what fits.

PRODUCT.md states the short promise and links here.

Linguagem predominante
JavaScript
Estrelas
1
Forks
1
Merge médio
3h 34min
PRs com merge (30d)
213

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de eizedev/pivotkit

Todas as issues de eizedev/pivotkit

Issues semelhantes

Mais issues de JavaScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.