search

input-output-hk / implementation-decisions

A repository for all concrete decisions made about how to implement the formal specs
Other
5 stars 5 forks source link

process proposal for adding/pinning down decisions #10

Closed commandodev closed 5 years ago

commandodev commented 5 years ago

This is to propose what the process could be to pin down the decision regarding what is present in the formal spec and to propose improvements to the current blockchain implementation.

For reference, I've based my thoughts on what rust lang is using for their RFCs process. I've tried to keep things open so that this repository can continue to be a central point of exchange for the developers to propose changes. I also believe this is good to keep things in the same place: one place to refer from.

May I also suggest we rename this repository to something more generic cardano-improvement-proposal ?

closes #1, succeeds #9

kantp commented 5 years ago

Thanks for this, @boothead!

Let me ask a couple of question to make sure I fully understand the procedure:

NicolasDP commented 5 years ago

The way I see it is that only concrete decisions should be put in if and only if the spec part is done already. This is consuming the spec (within other things), not the other way around.

If you wish to update the spec, we then need to evaluate what impacts the change has in the current documents, if it deprecates previous RFCs, etc. If yes: we will need to add new RFCs to deprecates the previous decisions. This will allow the development team to move forward with something concrete.

commandodev commented 5 years ago
  • When a PR for an RFC is made, should that PR only be merged once the according changes have been made to the spec, so that the submodule can be updated with that same PR?

Good point. I think if we come across a case where an RFC causes changes to be made in the spec we should prioritize the speed of making the implementation decision so that the team who raised the RFC (and who are presumably implementing something at the time) should remain un-blocked. From that point of view we should go ahead and merge the RFC as soon as the proposal is accepted and not that the spec will change as a result in the RFC (although I noticed we probably need a section explicitly listing any consequences of accepting the RFC)

If we agree that this is the right thing to prioritize, then the question becomes: do we update the RFC (that's already been merged) with a note to reflect the changes in the spec after the fact? Personally I think amending the RFC with a link to the new PR which updates the submodule (and vice versa noting in the PR which RFC this update impacts) should be fine.

  • What if the authors of the specification, who are still working on the specs, decide to concretise things -- should they follow the same procedure? So, if I make a change to the spec, should I add a PR to this repository, which updates the submodule and adds another markdown file explaining the changes?

Yes I think so - if the spec is changed or the source of truth about something moves from being in an RFC to being in the spec that should be noted in an amendment or superseding RFC.

Thanks @kantp - these are exactly the corner cases in the process we need to think about - keep them coming :-)

kantp commented 5 years ago

@boothead Concretely, I'm currently working on adding all the changes and decisions from last week to the design document, and the team working on the formal specs is doing the same. For these changes, I think the RFC format is not the best -- it would be a massive duplication of information. I could see two alternatives:

  1. Adding a type of changelog entry to this repo, linking to the PR for detailed information (and bumping the submodule revision).
  2. Inviting both dev teams to do a review of the pr in the repo holding the document.
NicolasDP commented 5 years ago

Hi @kantp , this repo is more meant to consume the spec at a given point in time. This is why there is a submodule referring to a specific version of the abstract spec. If the author of the spec are changing something in the spec, they can. This repository, at a given point in time, can only refer to the currently supported version of the spec. This will allow the developers to be able to move forward with the concrete implementation.

If a RFC proposes to do something that is not in the spec or to do something slightly different or completely different from the spec : this is fine. The formal spec team can review that and update the spec if they believe it is useful or not.

I think it would be great to have a Changelog to track what changes are being done in the spec : but it ought to be in the fm-ledger-rule directory, not here.

kantp commented 5 years ago

Ok, that makes sense. Thanks, @NicolasDP!

dnadales commented 5 years ago

Sorry if I'm just rehashing previous questions, but I want to make sure I understand how the formal spec writers should use this repository, and what are our obligations.

Whenever I make an update to the specs, do I only need to check that no concrete decisions made here are affected? If so, and if I affect a previous decision, do I have to submit a PR with a new decision/feature (using XXXX-template.md) and link to the previous decision/feature that I'm modifying?

dnadales commented 5 years ago

If the author of the spec are changing something in the spec, they can. This repository, at a given point in time, can only refer to the currently supported version of the spec.

And do we want to submit a pull request to this repository with an RFC if we made changes in the spec which we think they should land here?

commandodev commented 5 years ago

Sorry if I'm just rehashing previous questions, but I want to make sure I understand how the formal spec writers should use this repository, and what are our obligations.

That's what this whole process is for - the more questions the better! :-)

Whenever I make an update to the specs, do I only need to check that no concrete decisions made here are affected? If so, and if I affect a previous decision, do I have to submit a PR with a new decision/feature (using XXXX-template.md) and link to the previous decision/feature that I'm modifying?

Yes that sounds like the right workflow to me

And do we want to submit a pull request to this repository with an RFC if we made changes in the spec which we think they should land here?

If the spec is updated and we want to pull those changes in here I think we should make a PR to update the submodule and use that PR as the medium to discuss which RFCs are affected (if any). If any do need to be superseded or amended we can do that in the same PR, and then merge the update to the submodules along with the new RFCs that desrcibe the concrete impacts of the changes.

@dnadales If you wouldn't mind, could you write up what the process should look like from the spec side in the README and send a PR? We might as well document both workflows in the same place.