RFCs and TIPs -- Introduction and Consolidation

Governance
1

Hi all,

I’ve begun working on a new idea for the project-- well, new to us. This idea is a well-established idea in many open source projects and we have something like it already in our RFCs.

The RFCs define protocol and architecture standards for Tari. They’ve been the domain of the core developers and are a great way to get familiar with Tari’s internals. However, they’re not set up for things like defining community governance, at least not in their current form.

I’ve created a draft Pull Request to introduce TIPs– Tari Improvement Proposals, meant to cover the wider case of things like community governance policies, best practices, or the charter.

In my current formulation I’ve conceived of them as distinct from the RFCs to avoid disturbing the existing work too greatly. However I’ve already gotten word that the core devs who have looked at this believe something I’ve felt in my gut as well-- that we should consolidate these so they’re variations of the same thing somehow.

There was already some work to better formalize the process surrounding RFCs, and TIP-1 provides much of the same.

My gut feeling is that ‘everything should be a TIP’ rather than ‘everything should be an RFC’, just because RFCs bring to mind only technical things (to me, anyway) but TIPs are being invented now and could have their scope expanded.

The simplest solution might be to just rename all RFCs TIPs, and make TIP-1 the next number in the series. However, I’m not sure if that’s the best path, and I welcome alternative proposals, especially from the devs who wrote the RFCs and would be most affected.

2 Likes
2

Yeah, our primary discussion was that there’s so much overlap between TIPs and RFCs that it kind of voids the need for both. Our primary suggestion was around the flow of how a new proposal is created and how one might be deprecated.

Only currently implemented tech should be in the RFCs, be that overly technical or not. The RFCs should be written so that you can understand what’s going on without having to go technical, but if you want to, you can — almost a layered approach, where you choose how many layers deep you want to go technically into the idea.

So our proposal was this:

  1. An idea starts here in the forum. It’s discussed, a formal idea is formed, and there’s some consensus that it’s a good idea.

  2. A formal RFC is written up on the idea.

  3. It gets archived as a p-RFC (proposal RFC). This formal RFC is then discussed and iterated on.

  4. It moves to either a-RFC (accepted) or r-RFC (rejected). An accepted RFC is not yet implemented, but it is due for implementation and the community has agreed to it. A rejected RFC is kept for archival reasons, along with the reasoning for why it was decided against.

  5. As the RFC gets implemented, it moves from a-RFC to RFC.

  6. If the RFC gets retired or removed, it moves to d-RFC (deprecated).

Let’s take an example like the Dandelion post here on the forum:

  1. It gets discussed here on the forum, and let’s say the community is in favour of it, so we move forward.

  2. It’s written up as an RFC and gets assigned p-RFC-MT-0001 for proposal, base layer (MinoTari).

  3. Here it’s discussed, and the community decides that TariScript is more important than Dandelion, so it gets rejected and moved to r-RFC-MT-0001, which records why it was rejected.

Alternatively, let’s say the community decides Dandelion is more important than TariScript. Then we do this instead:

3b. It moves to a-RFC-MT-0001.
4. When it gets implemented and merged in, it moves to RFC-MT-0001, and TariScript moves from RFC-MT-0201 to d-RFC-MT-0201.

3 Likes
3

@blackwolfsa That matches my read of the PR9. I can see how it would solve ambiguities around the RFC process.

I think that the TIP process might do the same-- the advantage with using the TIP-header standard would be that we don’t have to rename the files or move them to indicate their current status-- we just update the header.

In the TIP proposal, there’s a way to specify what ‘Type’ of TIP one is submitting. Right now, there’s:

  • Process
  • Best Practice
  • Product Direction

But we could just as easily add another category, like ‘Architecture.’

It occurs to me that the current PR collapses the meat of the TIP process by default-- so if you haven’t yet, be sure to expand the file to check it out.

The process is derived from OEPs, which are themselves derived from PEPs, done by the Python Foundation.

It would take some work to retroactively instrument the RFCs to use the new header, but it’s work we’d need to do on some level anyway for your proposal, since we need to comb through the history and see which RFCs were adopted, which weren’t, and which need updating. These varying statuses are also supported by the header.

For RFCs which weren’t adopted but which were merged in, we could set their status to ‘Replaced’ or ‘Obsoleted,’ though we could allow them to use the ‘Rejected’ status, which currently isn’t expected to be used for merged PRs according to the process, but would be fine as a concession for historical record of RFCs.

In the proposed TIP versions, the fact that a pull request is closed without merge serves as the record of the rejection (and contents), and so only TIPs that have been or are in some way ‘active’ are kept.

Otherwise a lot of your process is mirrored-- an idea could start anywhere, but it’s eventually turned into a proposal as a PR by an Author, assigned an Arbiter to usher it through the process.

It is then announced on the forum. People comment on the forum and/or the GitHub pull request directly. The Arbiter works with the author to verify that community concerns are addressed and that consensus has been reached.

Once consensus is reached, the status is changed to “Accepted” and then it is merged.

If a new proposal deprecates it, the new proposal will have a ‘Replaces’ field in the header to replace the old version, and the old version will be updated to ‘Obsolete’ and have its ‘Replaced by’ field set.

Would this address your needs for the RFCs?

1 Like
4

I want to put one thing out there: I personally don’t care what we call them—RFCs, TIPs, whatever. But I am very much in favour of a more structured approach. I’ll keep using “RFCs” and “TIPs” throughout this discussion so we can be clear about which method we’re referencing, but the names are interchangeable in my mind. We can call them bananas for that matter.

That said, we can’t just leave the RFCs as they are—they’re wrong and out of date. I’m busy fixing them one by one. I’ve held off on renaming them since we’re still in the process of finalising things, which makes review easier. I’m purely focused on the contents for now.

This is where I dislike the TIP approach as it currently stands: it’s a list of random ideas, and you have to open each one to see if it’s active and relevant. For rejected ideas, you have to search through GitHub’s closed PRs. If we merge everything and keep it structured, we can host it like we currently do with RFCs, where there’s already a section of deprecated RFCs. You can quickly scan them to see what’s what.

Regarding the arbiter—that’s something not currently written in anywhere, and it’s probably worth bringing in.

I’d propose something like this:

Idea generation. A very informal process where the community discusses an idea—on the forum, at in-person meetups, etc. This is a pre-step to avoid wasting the author’s or reviewers’ time on ideas that aren’t ready.

RFC writeup. The author writes up their idea. Here we can use an arbiter to help verify the integrity of the proposal. If the idea is sound and properly written up with a clear explanation, it gets merged as a draft.

RFC proposal discussion. This is where we should bring in the Tari Council. They should ensure all community feedback is considered, and where appropriate (perhaps enforced depending on the idea), input from technical and security experts. The proposal can be updated to address recommendations through an iterative process.

RFC finalization. The Tari Council votes on the idea and moves the RFC to accepted or rejected. Rejected RFCs should be updated to note why they were rejected.

RFC implementation. The Council and author work together to find someone to implement the RFC. Once the RFC is merged into the code, it moves out of “accepted” and into “RFC” proper.

These are fairly stringent steps, but they make it easy to follow the process and know where any given RFC stands. I prefer renaming the RFCs because it makes the status easier to follow from the outside, rather than having to open each one to check the header. We have to update them anyway in some form.

5

That makes sense-- though I think the current proposal of renaming RFCs might make this more complicated rather than resolve it, though.

All the links on the forum break and it’s not obvious where to look for people not already familiar with the process. Renaming it also changes what to search for-- it could now be one of several strings depending on what happened to it. You could work around this by maintaining a set of redirects, but that’s messy and seems error-prone.

We can already move the RFCs to a different section in the navigation, which makes it easy for people who are searching know where it stands. Adding the header solves the problem for people who are returning to the URL or following links, which I think will be the greater share of people over time.

I’m OK with letting drafts be merged for better historical records. It would also make picking the next number easier.

The current TIP process has the Arbiter making the call on whether community consensus has been reached, and in charge of leading the discussion there. However I’ve also written a segment noting that the Tari Council is over the Arbiter and can step in if there’s misconduct.

If the council makes the decision directly, they can vote it down more easily even when consensus has been reached. I don’t expect this to happen, but it’s a thing that’s happened in other communities, and having some basic check in place could make it less likely here.

The Arbiter is under the charge of the council for their duties-- if they’re misbehaving, the Council needs to publicly step in and do something. If the Council says they’re misbehaving and decides to remove them, that’s a socially costlier option, where they have to make more of a case to the community. This would be worth doing if there’s real misconduct, and expensive if not.

This additional bit of social friction on both ends makes it to where both parties are keeping an eye on each other and encouraged to cooperate, and the public is able to see more of the decision making process.

It also makes sure that each proposal is getting proper attention-- the council is a handful of people, none of which is making that proposal their specific responsibility, whereas the Arbiter is one person assigned to a task.

We can certainly clarify the role of the Arbiter’s duties to require that experts in the area weigh in and put a pause on things if they’re either not weighing in or not reaching consensus.

I’m OK with ‘hey, talk to others in a public space for a bit to make sure it passes the smell test before opening a PR’ being added as a specific requirement.

6

Changing RFCs is effectively changing consensus. This means the council needs to keep an eye on it and be aware. Its going to be slow, it needs to be slow. I am against putting this in the power of 2 poeple. And if the council has the power to take over, what real power does the arbiter have?

If the council can step over the community at any given time, it’s both a feature and a bug. The arbiter can merge something, the council can revert it, so why not leave it with the council?
If the council messes up stewarding the community, Tari dies, it goes to some fork or the council gets replaced. Either way, the arbiter has no real power.

7

The idea was more that the conflict between the Arbiter and the Council would cause a public squabble, surfacing issues earlier so that the community could react. The fact it would cause a squabble might deter some from even trying to act poorly, but would make it visible if that deterrance failed.

This is a strong point. The slowness is a feature, not a bug, since the cost of sending things through too fast is very high. What if we switched it up slightly?

Say the Arbiter not only reviews and merges the draft content but ensures that the process has been followed by the Author-- including posting it in the right places, gathering consensus, and then ‘certifies’ the TIP such that it can be reviewed by the council.

Then, the council reviews the proposal along with the evidence of process and consensus. This prevents the kind of slowness we want to avoid-- confusion around process and not having a point person to ensure it-- while encouraging the slowness we want-- making sure consensus is followed and the council is weighing in for the final say.

Would that work or do you still think the Arbiter should only be first PR reviewer?

8

mm, any kind of squabble will be visible, the whole process should be open and visible to the community.

But the more I think about it, the less need I see for an “arbiter”, I can see the need for an “expert”, if they and the arbiter are one and the same, then yeah there is a need. But apart from that, I see two main stakeholders:

  1. Author, they are the main stakeholder here and pushing for the idea to move forward
  2. Council, there main security is chain health, be that to keep the community involved in the project, or to keep it secure and stop bad stuff getting in.

So in line with that, I see the author pushing to get stuff moving forward, while the council wants to make sure the community is involved and happy, while also being sure the rfc is sound, having been checked by the community and experts.

1 Like
9

Agree with blackwolfsa’s concern about Arbiter power ambiguity.

If Council can override, the Arbiter either has no real authority or creates confusion about who decidess.

Suggestion: Separate facilitation from decision-making.

  • Process Coordinator (no merge power): shepherds TIPs through steps, ensures discussion happens
  • Technical Experts (advisory): review for soundness, not consensus

Both could be Council members who filter proposals before bringing to full Council for final decision.

Keeps things slow… while avoiding power concentration outside Council.

This also adds to the argument that the ideal Council needs to be an appropriate mix of technical, marketing, and business development backgrounds. Finding the devs to engage in these processes is a separate requirement.

1 Like
10

I don’t think the Arbiter’s role should be undersold here-- the work of initial review, facilitating discussion, and gauging readiness for vote isn’t trivial, and I expect it to compound as multiple proposals roll in. If I had to bet, I’d say that something like the Arbiter role will be instated by the council if it isn’t included now, just because my experience working on committees tells me that this will be difficult to manage otherwise.

However, if you’re really dead-set against it, perhaps we can instead note that all proposals should have an expert reviewer, rather than an arbiter? Making that explicit would be helpful.

1 Like
11

I am not against any role, like an arbiter, but it need to be a clear role with a need. If it someone we want to do an initial expert review in, then lets call it that, an expert review for soundness of the initial concept.

For some of the other tasks, like make sure the process moves along, I feel like the auther has a higher stake in terms of overall stakeholders to push foreward, and make sure it progresses.

Over the entire process we have many roles, and many stakeholders.
I can see the following:

Author - writes the rfc, pokes parties to make it move forward,
Expert - Does initial soundness review,
Council - ensure community is happy and involved, ensure expert/author does their job correct and project soundness stays true

12

I will add this here, perhaps we need to write all out “tasks” and assign the best stakeholder to them to see what we need.

With the Council + arbiter, the council needs to double check + verify the arbiter’s stuff anyway, so we can cut out he middle man and reduce effort.

1 Like
13

@blackwolfsa , could you give some insight into how this process was managed during Tari’s development within Tari Labs?

14

Ok-- I think I have enough information to make a revision. I’ll ping y’all when it’s ready for another look.

15

@blackwolfsa @PotR @Okz

Please check out the updated TIP. To get just the stuff that’s changed, check this commit.

This reflects the notes I’ve gotten here. I’ve also added @blackwolfsa as the expert reviewer. One thing not specifically mentioned in the TIP is the RFC-to-TIP conversion. I was about to write that up when I realized the existing RFCs jump all over the place in terms of numbering, so a straight up re-labeling may not be as straightforward as I thought, since I don’t think we actually start at TIP-8001 or whatever just because the highest numbered RFC is 8000. But I’m curious your thoughts.

16

yeah this is moving along into a better idea. I agree with the path there I think it makes more sense.

But I want to move along to naming this.
So your mention of the I realized the existing RFCs jump all over the place in is the exact reason why I dont like having the status etc in the header. There was actually some method behind the number:
1XX is base layer core rfcs
2XX is base layer extension
3XX is second layer aka ootle.

Having just a bunch of random numbers mean nothing from the outlook. You need to know or read ALL to know whats actually currently implemented or not.

I would like the docs to be very clear from the onset, to what part of the project they belong, and in what status they are.
if I see a-RFC-MT-250 or a-TIP-MT-250` for example, I know it related to minotari aka L1, it’s been accepted, but not yet implemented.
Seeing RFC0250or TIP0250I need to go and open it to see the status. And I have no idea what part of the project it belongs to without starting to read it. I am pretty sure we can add reroutes if the file path changes

17

For the most part this was written after we the actually coding.

Development was:
whiteboard discussions
Coding implementation
RFCs written after

As the code changed, the RFCs stuck where they are now.

We need to slow down now and go RFCs first

18

I’m a bit late here - but as someone that wanted to contribute to core development and found the process confusing here’s my .02:

I like the idea of TIPs. I think every crypto developer is well aware of the BIP process for Bitcoin, and this approach has been replicated across hundreds (probably thousands) of other projects. In fact, it was the absence of this process that confused me initially.
Want to submit a proposal? Just go to the github and submit a TIP! It’s easy and familiar.

I also really love the RFCs. I am not a rust dev. Now with AI where it is, I don’t plan on ever teaching myself a new language in the same way I once would have - so I will never be proficient in rust. Instead I need to rely on my AI coding assistant and documentation to help me understand the codebase. Keeping these RFCs up-to-date serves an essential and separate purpose to the TIPs - explaining how things actually work with the protocol right now. I’ve leaned on the RFCs heavily in my discussions with other community members, both developers and non-developers alike. I’d hate to see them disappear.

In my ideal world, we would have the TIPs for new development proposals/discussions, and then once finalized an associated RFC would explain how the proposal actually works as implemented.

19

I still very much like the header and the idea that the URL and ID/name of a proposal stay static, perhaps with only this one time change. However this makes me think of another way to do that which might encompass more of what you’re talking about.

I’d suggest we namespace the TIPs as follows:

  • TIP-PROC-XXXX for process improvement proposals
  • TIP-RFC-XXXX for code arch/algorithm proposals
  • TIP-PROD-XXXX for product direction proposals
  • TIP-PRAC-XXXX for best practice proposals

In this way, RFC can be a namespace within TIPs. All RFCs get renamed with the TIP prefix. A process TIP could then be written to specify the numbering system and expectations around RFCs in particular. You can further specify how different dashes and numbers work within a specific namespace for your needs, and they might be moved one last time in this case to incorperate -MT- or -OT- or whatever you like.

I still don’t want us changing the names of RFCs after they’re established (and this initial shuffle) because that means that the name of an RFC changes during discussion, meaning that many references to the RFC on the forums or chat will be altogether wrong. And the more state changes an RFC has, the more redirects we have to add (and remember to add.)

But the nav makes it easy to at least see what state it’s in. It’s easy to make it clear there and in the header. I don’t see any real advantage to renaming, and a lot of downsides. Unless you’re primarily reading the RFCs on the command line or in a file browser rather than the published site, the advantages don’t manifest at all, as far as I can tell.

No one’s planning to make them disappear :slight_smile:

1 Like
20

Your biggest objection to file renaming is broken links right?

My biggest reason for file name changes is to make it clear from the onset where each rfc is, and in what stage it is, and for what it is.

What if we do both? The RFC name and File name dont have to be an exact match. We use MD docs for the hosting. We have name each file a once off almost give it a small UUID name, for example, we do RFC-MT-TariScript-{ABCDEF} where {ABCDEF}is some random UUID type string to make the file name and link unique.

So then the current link for tariscript is: https://rfc.tari.com/RFC-0201_TariScript , it we could even leave this as is, the file/link. We rename the rfc to RFC-MT-TariScript-0201so that on the header, the link in the page, it shows that `RFC-MT-TariScript-0201` but the actual link stays the above link.

The actual md file name, and the displayed name does not have to match 100%.