discourage writing code before proposal is approved
Opened this issue · 6 comments
when a feature being proposed has already been implemented in part or in full, it leads to a sparse proposal document which leans on the implementation rather than stands alone and a bias toward what already exists. this defeats the proposal process altogether as the point is to agree on what a feature should look like and publish a document that is sufficiently detailed that someone can implement it from scratch.
at most a SIMD might include mock data structures or pseudo code to help describe complex logic, but even these should be kept to an absolute minimum and described as well as possible in prose.
--
i'm not sure we've decided on how to amend existing SIMDs, but this should fit into 0001 or its successor
when a feature being proposed has already been implemented in part or in full, it leads to a sparse proposal document which leans on the implementation rather than stands alone and a bias toward what already exists
Leading to a sparse proposal document should be squashed as a norm. I do know that Firedancer was interested in having a proof of concept for SIMDs as mentioned in the first community call. Video startting at ~10min, Notes.
i'm not sure we've decided on how to amend existing SIMDs, but this should fit into 0001 or its successor
This would likely be an amendment to SIMD 0001. Ethereum uses a "living" status on EIPs to note designs that can be updated in the future. We may want to consider adopting that framework as well.
i dunno. i could see poc after the design is at least generally vetted, but the proposal can't rely on it. i'm in prose/concept review mode, not code review. the bias is the most concerning part though. generally if someone's taken the time to write code, they're invested in that path and will be difficult to steer
--
there's also the RFC approach where RFCXXXX gets superseded-by: RFCXXXY added to its metadata, and RFCXXXY supersedes: RFCXXXX, that way you get links in both directions and retain a historical record
@t-nelson @jacobcreech How should we move forward on this? Happy to write up a "best practices" kind of SIMD doc that we can link in the contributing guide. I think writing PoC pseudocode to assist with discussion of a spec is fine. What's IMHO a bad practice is references to identifiers in the Solana Labs codebase. Those will eventually change with refactors and lose their definition.
i'm still of the opinion that a proposal should be prose dominant and that any reference code should be kept to a minimum. the document should be self-contained, not link out to a reference implementation, especially as a clarifying or exemplary device. perhaps a more general bar would be, "any reference code must be in-lined"
The problem is that the processes involved are incredibly slow. Writing the code ahead of time is often using "dead time" that can't be used to advance the proposal anyway. There is no obligation for anyone to accept the code, so the author is taking a risk that all of their work would be rejected; but that should be obvious to anyone involved and becomes a choice solely at the discretion of the author (i.e. whether or not to write code ahead of time).
Referencing code can help communicate intentions just as well as textual descriptions of features. Those references can be removed from the SIMD after review of those sections meets some level of agreement.
In addition, I personally find that actually working in the code reveals issues that were not considered previously. I am personally not particularly good at "imagining" all of the aspects of how a proposed feature will interact with existing features, and actually fleshing the implementation out has benefit for me because it informs me of the stuff I didn't think of.