Please ensure the results of RFCs are clearly documented

Data Management
#21

My opinion is that the follow-through of implementing the results of RFCs, including updating the authoritative documentation, is what is lacking. Some of that may be because people don’t know where to update the documentation or are afraid to because the canonical locations or documents may be in flux. Some of that is the “RFC assigning work to other people” problem. RFCs where the proposer is the implementer are easier in this regard.

Having adopted RFCs that are not implemented is a problem. I think some of these can be partitioned into a policy statement and then code implementation of that policy statement. The policy statement should be immediately recorded in authoritative documents upon adoption. The code implementation can be left for tickets. If we are lacking in authoritative documents, we should create them.

#22

Oh, wow, that’s a dangerous message! :smile:

I’m also not sure it’s really what I was aiming at here. I’m worried that we as a project regard adopted RFCs as normative. That is, for example, the version of Python we support changes at the moment somebody hits the “adopt” button on the relevant RFC. That seemed to be the message being propagated by some of the Bootcamp discussion: we had an RFC about coding standards which said do X, so we should now do X, regardless of what our docs say.

I don’t think this is smart, because it means individual developers are left peering at RFCs and trying to work out what the current best practice is. Rather the documentation should be normative: adopting an RFC provides permission to update the docs, but nothing more than that. There’s no need for Jim to be squinting at RFC-45 and wondering what it means: if he wants to know how we currently handle copyright assignment, he looks at the developer documentation, end of story.

I do think it’s fair that T/CAMs should take responsibility for allocating the effort to update documentation or make other changes to implement adopted RFCs (and, actually, I don’t think it should be @jsick’s job to scour the RFC project cherry-pick results into documents – that should be the job of the proposer). But before we can just regard it as a T/CAM problem we need to agree on what an adopted RFC actually means.

#23

which is why I keep wanting “Implemented” to mean “job done” and “Adopted” just to mean “permission has been agreed to proceed with the proposed change”.

#24

Adopted should, I think, almost always mean there is some immediate change to the authoritative documents, whether coding standards, design docs, or other. As I said, code changes as a result of those document changes can come later. The point is that no one should ever have to refer to an adopted RFC after its adoption.