doc: add rc version guideline #468
Conversation
|
Kudos, SonarCloud Quality Gate passed!
|
| @@ -6,44 +6,15 @@ AsyncAPI is a specification for defining message-driven APIs. We're on a mission | |||
| ## How to Get Involved? | |||
| AsyncAPI is an open-source community-driven project. We're happy to receive contributions from different people, no matter your skills or your area of expertise. There are many ways you can contribute to the project, not just code. There is always a need for: documentation, design, writing, evangelizing, code, issue triage, and more! We also welcome financial support and donations. Check out the [contributing guidelines](./CONTRIBUTING.md) to learn more. | |||
|
|
|||
| ## Timeline | |||
| ## Versioning | |||
There was a problem hiding this comment.
I don't think we have to explain versioning on a Roadmap document. Also, versioning is already explained on the spec: https://github.com/asyncapi/asyncapi/blob/master/versions/2.0.0/asyncapi.md#asyncapi-version-string.
And there's a link to the latest spec in the readme already: https://github.com/asyncapi/asyncapi/#the-specification.
|
|
||
| We're working hard to reach version 2.0.0, which will be full of great new features (and bug fixes.) | ||
| ### Release Candidates (RC) |
There was a problem hiding this comment.
I'd not talk directly about RCs here. Maybe we should call them "prereleases" (as defined by Semver). We may also opt for -alphaN suffixes before we call them a "release candidate". RC should only be those versions we believe are done and therefore we want people to try and tell us if they're really done or not.
Also, not sure this is the right document for this information. Maybe we should have a separate VERSIONING.md document?
There was a problem hiding this comment.
Having separate RC and Alpha releases will just make it more confusing. To make it clear, RC doesn't guarantee anything. It's a candidate version for the upcoming release.
I would suggest we only follow one convention for now and not make it too complex atm. If in the future, we need to separate out we can.
I like the idea of explaining everything about RC in VERSIONING.md. Couldn't find the best place for it. Will create it now. 👍
There was a problem hiding this comment.
In some cases, we may find it useful to flag a spec version as alpha because we want to release different packages with the same version to see how everything fits together. We'll most probably do it to try things out separately, knowing it's far from being close to stable. Alpha is just another step in the software development cycle where you're experimenting, let's use it. A release candidate is a version that could potentially become the final version: https://en.wikipedia.org/wiki/Software_release_life_cycle.
For instance, I may want to release 2.1.0-alpha1 which only contains your MessageId proposal, so the team can start working on the tooling to support it. 2.1.0-alpha2 might contain a second feature we want to include, and so on. In these cases, we don't to communicate the users that we have a release candidate because we know it's far from being it. But that's ok, just because we release them it doesn't mean we have to communicate about them.
| :arrow_right: [Backlog](https://github.com/asyncapi/asyncapi/projects/4) | ||
|
|
||
| The purpose of the backlog is to temporarily group issues that may be considered for the future. Please, note that it doesn't mean they will get implemented, however, there is a big chance. | ||
| You can check upcoming features and in-progress tasks thorugh [ZenHub Dashboard](https://app.zenhub.com/workspaces/asyncapi-initiative-5e541969da30b0bc34628b22/roadmap) |
There was a problem hiding this comment.
Thanks for removing the junk here. Let's not point to Zenhub as you either need an account or the extension to see the information. Let's use shapeup.asyncapi.io instead. Actually, this whole document should probably be removed and we just add links to README pointing to shapeup.asyncapi.io.
|
@WaleedAshraf describing release process is a more complex task and we should not document only RC-releases process whithout knowing what is the release process in general, we also need to discuss:
it should be well discussed and I'd love to see a flow diagram that explains it. |
It would in same place as it is now. But on a separate branch.
Yes. Everthing that is released will be merged to master.
For now, RC version will only remain in github repo, on specific branch and on npm.
Same as we do now.
Yes
Create PR against RC branch, and it will be merged after approval. New branch will be created for the new RC version, from previous RC version. In the end, the latest RC version will be merged to master. Also, I don't think we need a flow char for this. This is a common process in almost all open-source projects :p |
|
I think we do need a flow chart for this. This is a common way of working on open-source projects but it's not the only one and we don't have to assume everyone is experienced with these workflows. Also, I don't think we have to keep older versions of the spec in a separate file. We can link to git tags/releases instead. This way, there's only one file for the spec and it doesn't necessarily represent the latest stable version, i.e., it may contain unreleased content. Just like we do with software. It would also allow us to use conventional commits easily. Anyway, these things need to be discussed, defined, and properly documented. |
I think we are mixing needed VS wanted here. For sure we can build nice flow charts, fancy UI, or whatever we want, in the future. But I'm sure we don't need all this ATM for at least for this PR. I don't consider it a blocker.
Yes. That would be even better. 👍 |
as I said, people often confuse schema with spec, but schema doesn't represent the spec 100% so it should not be there where spec is
why separate branch per RC? in my opinion it is branch for version, and from this branch we push RCs until we are happy
Well, I'm not native, I do not see much difference between needed and wanted 😄 I want it as I need it to properly understand the flow, and want others to clearly understand it too
The problem is it is not common. Example: you answered above we would create branch per RC and in my opinion we should not (as wrote above in this comment). It is really not common, there is no single ultimate release process for all projects. So it is all about properly documenting the process, like for example K8s team is doing https://github.com/kubernetes/sig-release/blob/master/release-engineering/release-notes.md. Nothing fancy 😄 but clear visualization that helps in discussion. Many things we do are not written everywhere so approach like
yes, definitely |
|
Well. It seems too much work for me ATM. My assumption was that we could start with something simple and refine it with time. It seems that's not going to work in this case. I'll see if I can find more time this weekend (probably not) otherwise I'll close this PR. Maybe someone else can pick it up. ;) |
|
@WaleedAshraf yeah, this is not a trivial task and not possible to solve with small steps without clear overall plan. This is why we always say to first work on issue level, discuss and clarify there instead of jumping to PR first, it saves a lot of time 😄 |
|
What makes it impossible is asking for everything at the start and not prioritizing what we need atm, and what can be done in the future. ;) |
|
well, as always, it depends 😄 this is why it is better to first have longer discussion than jump into execution ;) that is what contribution guides are for, to follow them 😄 btw, I saw you created a branch in the upstream, please remove it |
|
Yup. Sorry about that. My assumption was that we are aligned with the priority and importance of the tasks. Which branch? |
|
ah, sorry, it is another branch from another pr https://github.com/asyncapi/asyncapi/tree/issue-458 |
|
Yup. It's for the above PR #461 . I need to delete it? |
|
no, but please remember next time that we all work through forks |
Closes #463
I have removed the outdated timeline as it was not valuable anymore.