Open Noviny opened 4 years ago
@JedWatson and I had discussions about this last week. The end result was kind of a wider discussion about APIs and how public or private and they are and the publish vs not publish and open source vs closed source is another part of that spectrum, the thoughts are currently living in a comment in the README:
Maybe the stuff about what sections apply more or less should be a part of this?
closed source never published means semver is unimportant
I know this isn't your main thing here but isn't this not totally true because semver would be useful for packages on private registries/scopes?
Hm. That's very related but a very different way to group concerns.
My goal with these categories was to give us really easy flows through the docs (or encourage us to write for the flows) of some very big, repository-wide, before-you-start decisions, which ripple through. You're right that they exist on a spectrum alongside between modules and within a module publicness, but the point where you need to know about the concern are quite different.
I'm assuming that was surfaced in your chat as well though.
Maybe the stuff about what sections apply more or less should be a part of this?
Pretty much this, but also being able to add notes like:
If you do not plan to publish your packages, you may not need to care about bumping the versions of your packages
As well as being able to tie into "You are starting a monorepo, use these questions to establish if you are public/private, publishing/not-publishing"
closed source never published means semver is unimportant
I think if it's never published semver becomes irrelevant. You're right for closed source, private publish it's still useful.
SGTM, happy to talk about these categories as a separate thing. There are already some "this is only necessary if packages are being published" notes in some sections btw.
There are already some "this is only necessary if packages are being published" notes in some sections btw.
Honestly one of the prompts was this was seeing them and having a clear idea of what these categories are and stating them. I'm sort of thinking about this 2 * 2 matrix as our 'users' for who we want to address these docs at.
Was looking at breaking down types of monorepos we care about and there appeared to be two major divides:
Planning to codify these two dividing lines in the docs, and then where appropriate try and call out where sections are more or less likely to apply (closed source never published means semver is unimportant, but you may still want a changelog for future devs etc)
Sanity-checking before committing to master
(long term we may want different starter guides for these?)