Preview: https://asamalik.fedorapeople.org/tmp/docs-modularity-pr23/modularity/making-modules/naming-guidelines/

• Don't use stable naming anywhere. It is really bad idea. stable == dead.
• Probably use nodejs with streams 6 + 8 is better than having 9.6 + 10. It is confusing for ppl.
• Get rid out of golang-ecosystem in examples. It is leftover from modularity v1.
• Use master instead of experimental.
• Add hint about default profile.
• Rephrase section about package naming. I would probably even remove it.

Thanks for the feedback! For the record, we've also discussed this on #fedora-modularity, so I'm also using that feedback in the change.

Don't use stable naming anywhere. It is really bad idea. stable == dead.

There is a case when it makes sense, but explanation didn't make it clear. I've fixed that explanation.

Probably use nodejs with streams 6 + 8 is better than having 9.6 + 10. It is confusing for ppl.

I agree. In the end I've included both, nodejs 6 and 8, and postgresql 9.6 and 10 with an extra note about the streams, because I liked the "client" and "server" profile example I couldn't use with nodejs.

Get rid out of golang-ecosystem in examples. It is leftover from modularity v1.

It's a real example, though. Could such pattern be used for stream expansion over multiple versions of runtime? Either with a build for each, or just a single build + runtime compatibility with all?

Use master instead of experimental.

Developers usually know what master is, but what about users? I think something like "experimental" better communicates that message, but that word could be too long or sending the wrong message in some cases.

So in the end, I've used "latest" and extended the comment to better explain the cases when this should be used. Also, there are already some modules using "latest" for this exact purpose.

Add hint about default profile.

+1

Rephrase section about package naming. I would probably even remove it.

What I wanted to say here is that Modularity introduces no changes in this regard. Rephrased.

I might make example 2 include a hypothetical example like "Includes postgresql and the compatible version of python-pgsql". This would serve to reinforce that modules can be more than one package but should be named after their primary purpose, in this case "postgresql".

We should also note that compatibility on non-technical fronts is also important. For example, a package that maintains exactly the same API but has a significant visual and UX overhaul probably belongs in a new stream. Or to put it another way, human interaction is an interface too.

You use XXXX.MINOR for the CalVer but then immediately refer to "version" where you (I think) mean "MINOR".

Additionally, what is the "serial number"? You reference it but don't define it.

I'd rephrase this as "The module stream name is assigned by creating a branch of that name in DistGit and building from it. The Module Build Service will automatically set the stream name of the resulting module to match."

Do not use "i.e." here. You probably meant "e.g." (I.e. means "this and only this". e.g. means "This is one of many possible examples). Use of "etc." with "e.g." is redundant.

You're making some very good points, @sgallagh. Let me do everything you said.

Looks good to me now. Go ahead and merge it.

Awesome, thanks all for the review!