doc: add a migration guide from v0.11 to v0.13

Open
  • Is something wrong?
#397 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
65/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
documentation

Research direction

Start with doc/migration-v2-to-v3.md and inspect the current API and generated-client changes described in issues #379 and #380. Write doc/migration-v0.11-to-v0.13.md covering the listed symbol mappings, lifecycle, call patterns, code generation, and downstream checklist; fix the broken link in the existing guide without otherwise changing it. Done when users can follow the guide to migrate and regenerate compatible code before the next tag.

Written by the indexing model from the issue text.

Description

doc

Problem

Users of v0.11 have no guide to the API changes in v0.12 and in the next release.

  • v0.12 contains the API redesign: Config and NewConfig, typed call handles, the server and peer configuration, and the close function returned by NewConfig.
  • The next release adds the generated service clients (#379, #380): calls are methods on SClient (configuration calls) and SNodeClient (node calls), and the call functions and ConfigContext/NodeContext are gone.

doc/migration-v2-to-v3.md covers only the earlier QuorumSpec-to-iterator migration.
Its line 4 also links to issue-redesign-migration-guide.md, which does not exist.

Proposal

Write doc/migration-v0.11-to-v0.13.md, and keep the v2-to-v3 guide unchanged except for the broken link.
The guide should cover:

  • a table that maps old symbols and constructors to new ones;
  • cfg, err := NewConfig(...) plus defer cfg.Close() becomes cfg, closeFn, err := NewConfig(...) plus defer closeFn();
  • the server lifecycle and peer configuration (WithPeers, ServerContext, ConnectedClients);
  • typed call handles, lazy dispatch, and the rule that a terminal method is used once;
  • one-way calls: Send, Async, and Wait;
  • the generated clients: NewSClient(cfg), NewSNodeClient(node), and node calls that take the node as an argument;
  • regenerating code, and the GenVersion/MinVersion check that rejects old generated code;
  • a checklist for downstream repositories.

Write it before the next tag, so that the release notes can link to it.

Dominant language
Go
Stars
149
Forks
15
Avg merge
1d 3h
Merged PRs (30d)
44

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from relab/gorums

All issues in relab/gorums

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.