Closed carloslancha closed 5 years ago
izaera
commented
6 years ago Maybe you can create a breaking changes document similar to that of the portal (which BTW was inspired by FreeBSD’s breaking changes doc).
If you update it in every PR that has a breaking change then you just need to scan through that doc in order to see what needs to be changed.
carloslancha
commented
6 years ago @izaera and what about new features/components/API?
julien
commented
6 years ago @carloslancha for new components, features maybe we could do the following:
bryceosterhaus
commented
6 years ago I've seen projects use emoji's in commit messages and generate changelogs from that. We could adopt something similar to keep a better record of what each commit is doing, rather than rely on a specific phrasing.
For example: https://github.com/carloscuesta/gitmoji https://github.com/dannyfritz/commit-message-emoji https://github.com/dannyfritz/funcdash/commits/master
izaera
commented
6 years ago @izaera and what about new features/components/API?
How is it possible that you need to adapt old code to new features? 🤔
If it is not adapting, then you should document it, I guess. But if you are using github issues for every work being done and you label it enhancement then you are done. Don't you?
izaera
commented
6 years ago @carloslancha ☝️
izaera
commented
6 years ago For example, this should be a changelog and if it is correctly labeled it should contain all info, I guess...
I'm also thinking now that maybe, if you create a breaking-change label, you could gather the breaking changes from there too... 🤔
matuzalemsteles
commented
6 years ago Leaving just a few of my thoughts on this. Let me know if I was not so clear with the information, I'll try to explain it again.
We really need to improve the way we're labeling issues, it's really helpful to know where the real issues are in our project, it will also help other people to contribute. So these are some label proposals that we can make with each new issue that will be opened and the ones we already have.
I'm following as examples some repositories known React.js (I really like how React handles this 🙂), Gatsby.js and Angular and bringing a bit to our reality.
We can organize our labels by categorization, it helps us know where the problems are. Since our repository is a monorepo with many packages and some different things.
| Category | Notes |
|---|---|
| Component | The component reflects where the problem is located (e.g Clay Components, Charts...) |
| Type | Reflects issue type (e.g Bug...) |
| Status | Group of labels that reflect the progress of the issue |
| Resolution | Group of labels reflecting resolution of issue |
| Browser | When some issue only affects a specific browser |
| Label | Category | Notes |
|---|---|---|
| RFC | None | Similar to the RFC that are used in React.js, Ember.js, Gatsby.js and Rust, but to mark problems that are opened as a proposal for changes or to include new things |
| Infrastructure | Component | They are used in problems that are related to monorepo infrastructure, build, process automation... |
| Clay Components | Component | Issues related to Clay components. (e.g ClayCard, ClayLabel...) |
| Clay Charts | Component | Issues related to components of Charts in soy or React |
| Generator Clay | Component | Issues Related to Our Clay Component Generator |
| Clay CSS | Component | Issues related to Clay CSS |
| Documentation | Component | Issues related to documentation in general, be clayui.com or other means... |
| Accessibility | Component | Issues related to accessibility in general |
| Clay site | Component | Issues related to website infrastructure or other things outside the documentation |
| IE | Browser | Issues that happen specifically in IE browser |
| Chrome | Browser | Issues that happen specifically in Chrome browser |
| Safari | Browser | Issues that happen specifically in Safari browser |
| Firefox | Browser | Issues that happen specifically in Firefox browser |
| Breaking Change | Type | Issues that caused some breaking change, whether in API or behavior change... |
| Bug | Type | Issues reporting that Component is not doing what should be done |
| Epic | Type | Issues that are opened as an Epic, that there are many things to be done |
| Discussion | Type | Issues that are open for discussion of some change or to gather information |
| Enhancement | Type | Issues that are open to bring improvements or refinement of code |
| Feature Request | Type | Issues that are open to adding new features |
| Regression | Type | Issues that are open that caused some regression |
| Blocked | Status | Issues that are being blocked by other tasks |
| Help Wanted | Status | Issues that are in need of some help |
| Next Release | Status | Issues that will enter into the next release |
| Duplicate | Resolution | Issues that are duplicates |
| Wontfix | Resolution | Issues that will no longer be worked on |
| Needs More Information | Resolution | Issues that need more information to be labeled correctly |
Let me know if I've forgotten something or if something is redundant.
I really like @izaera's idea of using milestones to be like a changelog, if we correctly use the labeling of issues, it will help enrich the log.
Actually our versioning system is a bit confusing and does not say what we are really doing here, maybe we should go with the different versioning for each package instead of launching a new version for all packages and they follow the same numbering.
We can follow semver.org to help people identify when there is a breaking change or a new version, this will be reflected in the numbering of each package and will be clearer. Once we follow this, it will help minimize problems with new and existing component versioning.
Semantic release is a fully automated version manager, it is based on keywords in the commits to be able to generate the next numbering of the package.
It was made to work only with one package and this makes bad adoption for the repository based on monorepo, there are some alternatives that the community has been creating based on it and they are working on it.
We do not have a versioning policy, to give people time to migrate quietly, since Clay's adoption is increasing. I suggest looking at what React has been doing, I really like this approach and we make sure developers are happier to do migrations..., for exemple.
We have to create release notes with information that we think is important, breaking changes, new features, new components, API, Accessibility strategies... we already do that, but maybe we should expose this to clayui.com and direct there when we do a post on the Loop for example. This will help to centralize our information and people will not be lost any more when a change happens. This helps people who are not Liferay. I see that it is not necessary to do this directly, only when it is things that we think it is important to communicate.
izaera
commented
6 years ago I would also like to say that I'm using issues as a way of tracking changes to the API much in the same manner as laws are written 😱 . Let me show an example:
If you look at this issue you will see that the first line says:
EDIT: Please see #231 before relying on this implementationAlso, the next line says:
This overrides #187, which specified that the user could specify the Web-ContextPath in the package.json file.This effectively links three issues together that cause changes in the API (in this case a config prop is moved to different places) between them so that users can always follow the history and so that we can, after releasing, tell @mwilliams2014 what needs to be changed in the docs.
The concept is similar to how laws are written in Spain (I believe is a bit different in the USA but you can get the idea). What we do is writting v1.0 of a law, then when an ammendment comes (v1.1) we create a paragraph at the end of the law that says what it is overriding/deprecating from v1.0 and so on. When a lot of versions have come out (imagine if you are in v1.17) and it is getting messy, we do a revision where all ammendments and the original law get fusioned and call it v2.0. In our case, the revision would be the final docs where only the last version of the API is explained (even if the tool is still supporting the deprecated ones).
As you can see, developers were not the first to invent version control (it was the Romans) ;-P.
jbalsas
commented
6 years ago Thanks everyone for the great conversation! I like a lot some of the ideas that have been thrown around:
clay-css package. When it changes, I think lerna will force a release of all of them... which might end up being the regular case anyways. We can try it out if you all agree. @carloslancha?CHANGELOG and RELEASE NOTES. Do you think we can autogenerate these confidently, or does this need to be done manually?matuzalemsteles
commented
6 years ago @jbalsas
I went ahead and updated the label taxonomy as proposed. @matuzalemsteles, could you go through our open issues and tag them accordingly so we have a starting point?
sure.
Finally, I'd love to see a more specific proposal about how to better manage the CHANGELOG and RELEASE NOTES. Do you think we can autogenerate these confidently, or does this need to be done manually?
I can prepare something more detailed in my point of view and we can discuss on top of it what to improve, but I believe we should continue with the generation of Changelog self generated, it helps to know what came in, we do this well actually. But perhaps one of the things we lack and describe what the real modifications, whether they are big or that we think it important to put as a highlight in some blog for example or in the release tab of Github. Here are some examples to look at:
I just want to say that we do not need to make Releases notes in every version, but only in versions that we think it is important to highlight and explain the reasons why we made the change, I think in this way we will be more transparent with our developers and we will create a approximation with them of what we are doing here.
jbalsas
commented
6 years ago Hey @matuzalemsteles, I think this is then something more manual and tied to the review process... as reviewers, we need to get used to make more questions and take notes or make sure things will be properly explained and documented. Do you we could do that somehow?
matuzalemsteles
commented
6 years ago hey @jbalsas, Yes it will be a manual work the releases notes, I think I can work on the creation of Releases Notes and if necessary we created a communication in our "blog" at clayui.com. I will work on a more concrete proposal during this week, how we really should deal with it, I will try to look for more examples to help us understand.
matuzalemsteles
commented
5 years ago I'm closing this since we already have a good definition of our workflow now. If you have any suggestions feel free to open another issue.
Hi!
Right now we're having some problems identifying what exactly has been made for each release looking at the CHANGELOG.
For example, once a new version is released we need to update Portal's versions and update the APIs that changed or any breaking change. To do so the only way we have now to know what we need to do is going through each pull request finding out what is needed to be updated.
So we need to
Let's go! Proposal time! ;)