Some more description or a pointer to a discussion about the purpose of this would be helpful.

Well, how about we discuss this right here, as described in the current version of RDM0, available in this PR? See section 1. in doc/memos/rdm0.md
Can you be more specific as to what should be explained more in detail?

I think usually if you propose a new feature in a PR it's helpful to state the purpose of this feature in the PR description. Apparently, here you are proposing a RFC memo format that can be used to document certain procedures, interfaces, BCPs etc for RIOT, right?

Right.

This is somehow similar to TEPs, right? I remember that we discussed if we want to have something like this for RIOT some time ago and the conclusion was that we weren't sure if this may introduce too much overhead or not. Are there any recommendations what exactly should be described in these memos?

What is IMO missing is some statement about when such a memo/RFC is required. Do I have to write a memo first before I want to introduce a new interface or component?

Also, should one cite one or more memos in a PR?

Concerning overhead: such memos are too much overhead compared to what?
AFAICT the consensus is that there is the need for additional documentation, in a form that is more "official" and more "stable" than the wiki.
This is a proposal to implement that in a somewhat standardized way.

Concerning overhead: such memos are too much overhead compared to what?

To not having them. 😉

I wonder if this discussion should not rather happen on the mailing list. These things tend to get overlooked by many people in the issue tracker.

I'm not sure if we should "standardize" when a memo is needed.
It can be event-driven and consensus-based: some people deem a memo useful or necessary, so they write one and propose it via a PR. It is then judged, discussed and refined as needed at this moment (it may also be turned down).
Once published, a non-deprecated memo MAY be used as reference to back-up some technical argument for/against another PR.
In particular, if a PR clearly violates the principles of some related (non-deprecated) memo it should justify why, and if the reasons are deemed valid, a new memo is probably needed soonish ;)

I just wonder if people will really write these memos voluntarily, but I guess future will tell us.

concerning moving this discussion to the mailing list: it would defeat the process I'm describing in this PR (which relies on typical PR discussion on GitHub) so I guess you'll understand I'm not voting for that ;)
And: the target audience here is the maintainer community, the vast majority of which are paying attention to GitHub issues/PRs, don't you think?

No one does anything without a purpose, indeed ;)
The assumption here is that some core maintainers feel the need for documentation that goes beyond wiki, emails or doxygen.
If this assumption is wrong, no need for any overhead.
Else, let's discuss this.

concerning moving this discussion to the mailing list: it would defeat the process I'm describing in this PR (which relies on typical PR discussion on GitHub) so I guess you'll understand I'm not voting for that ;)

Not sure this will work, but we will find out. However, I think we may use Github-only for proposing these memos (if we agree to go with this approach) in the future, but for having the initial discussion about this approach itself, I would think that the mailing list would be the best place.

And: the target audience here is the maintainer community, the vast majority of which are paying attention to GitHub issues/PRs, don't you think?

Well. there's a maintainer mailing list, but actually, I tend to disagree here: the target audience here is the whole RIOT community.

Well. there's a maintainer mailing list, but actually, I tend to disagree here: the target audience here is the whole RIOT community.

The target audience of the memos is the whole RIOT community, agreed.
But the target audience of this particular discussion is the maintainers, as they are the ones who would write/ACK the memos, if we decide to put this in place.

Do we need this kind of formalism?

I imagine a change that I want to introduce which is serious enough that it would apply for an RDM. Usually, after a long period of subconsious planning/architecting, I start writing a prototype implementation to see if the idea is viable. If it is, I clean it up, then create a PR (with RFC tag). People take a look, comment, bash, critizise, gratulate, help, ... and possibly after a while, the code is clean and documented and the general idea is accepted. The PR ripes, and at some point, we merge.

Now at what point would I write an RDM?

How about "retrospect" documentation, such as the device driver guide and the series of BCP and design rationale docs like that on the HAL that @haukepetersen is in the process of writing?
OK, technically we might be able to keep that in the wiki to some extent.
But would it not be more appropriate to have a more official, more permanent, citable memo on that kind of topic?
It seems to me that, as RIOT progresses, diversifies (and as core maintainers come and go, or change focus inside RIOT) a need emerges calling for some BCPs, and other high-level design rationale documents which capture the consensus at some point, and which could guide upcoming developers/maintainers -- beyond mining a slew of old PR discussions to decipher such rationale. Such documentation could be best expressed as memos.
@haukepetersen any opinion on that, since I cite you as concrete example?

But would it not be more appropriate to have a more official, more permanent, citable memo on that kind of topic?

Well, definitely nice to have. But unfortunatly not for free. I know I'd hate writing these documents.

Let's not forget that they say TEP's had a big part in TinyOS' slow and painful death. ;)

(just realized that it would be better if the memos had titles ;)

@kaspar030 well no one forces you to write a memo you don't want to write ;)
At the same time, I seem to recall you recurrently wanting to write up some BCP on some topic and/or some document of the type "BLAH considered harmful".
Is my memory playing tricks on me? If yes, sorry ;)
Else, would memos not be a good candidate for that?

Let's not forget that they say TEP's had a big part in TinyOS' slow and painful death. ;)

But that was because TEPs were mandatory for implementing a new feature or releasing a new version, right?

From my perspective it's gonna be interesting to see if we find a good trade-off between not making this mandatory and still motivating developers to actually write these documents.

squashed and rebased.
@danpetry @miri64 @Others care to ACK too?

If down the line we feel like updating the format, or moving RDMs to a separate repo, we could do that.

I'd still be up for this, but agreed that we should get it in and start using it. I'll go with the momentum and...

ACK.

@danpetry OK (you need to ACK through the dedicated reviewer interface in GitHub ;).

@smlng you OK to run with this for now?
As per RDM0 we need a 3rd ACK ;)

Another advantage for keeping it in the repository is that we can organize the subject of the RDM in a repository project together with the RDM PR. Having it in a separate repo would require an Orga project, just to include the RDM.

organize the subject of the RDM in a repository project together with the RDM PR.

this only holds as long as all RIOT related code is in one repository. But IIRC there are many ideas and lots of effort in the direction of allowing external code (drivers, boards, etc) to be more easily integrated with RIOT.

this only holds as long as all RIOT related code is in one repository. But IIRC there are many ideas and lots of effort in the direction of allowing external code (drivers, boards, etc) to be more easily integrated with RIOT.

That doesn't change the fact, that with putting it in a separate repo we always need an orga repo. This would include when there is a new effort to make a new featureX within the RIOT repo (while when the RDM is here and still under discussion while some initial implementation work is done it could all live in this repo). I expect that most of the RDM-triggered features are large enough efforts to justify a project, so this is something we should consider.

I fear that handling RDM in the RIOT repository will stall their progression from draft to standard (or what ever we want to call it when they are finished), because we currently have 400++ open PRs and thus RDMs will just be some more on top of that number.

Having a separate repo for this will make the (editorial) process of reviewing and shaping an RDM to its final state (IMHO) easier and more visible. Also I think, there are community members not so much involved in adding feature to RIOT (i.e. coding in C) that might help here as document shepherds (see IETF) or others that contribute tooling around RDMs.

Also, do we really want to have Murdock compile and test RIOT when someone just wants to PR and RDM? I know we can add (yet another) exception in our CI toolchains to work around that, but then we might want to run certain (style, grammar, format) checks on RDMs, too, which might not be useful for all the other files in the RIOT repo.

+1 for an external repo, and it seems to me like the consensus in this discussion is towards that.

We just had a discussion in the weekly meeting where the consensus amongst those present was towards merging it soon in its current state, and then iterating as we get a better feel for how people are using them. Including where they live, additions to the format, and additional processes. IMO this is a good approach which will allow us to home-grow our own RDM process and doc format - which is best suited to us - rather than re-use someone else's.

Addressed all comments (except moving to separate repo ;)
squashed and rebased.
Do we have one last ACK ?

Travis found another trailing white space though ;-).

damn. trailing white space hopefully fixed now. Let's see Travis.