docs(Readme): Add version notes #54
Conversation
Updates the README to speak to how to handle changing material design versions. Resolve HomeServicesOfAmerica#53
|
I should say a little bit more about the rationale behind the approach outlined in this PR, and why I think it merits discussion. Neither the documentation of material design spec or of the material components web library are versioned the same way Material UI is (where you can select a version and see the components at that point in time). They both always show the most recent version, material components in the case of material-components-web and material design of the case of the spec. While I do think emulating the styles at a selected release of the material components library has a lot of advantages, it does create a situation where we can't use any of the documentation or visual aids provided by either material-components-web or material design, since those are 'living documents' not pegged to any particular version. Our only way of knowing if a component is correct is to download the material-components-web package at that version, and comparing them side by side to see if the styles match exactly. If we're ok with being completely tied to their implementation, I'm 👍 on proceeding with it - however, it does mean we'll always be basically copying their implementation because there's no snapshot spec (at least as far as I can find) we can refer to outside of their components. The way of proceeding proposed by this PR takes the view that the intention of the library is to match the material design spec. As soon as something in the spec is updated, the affected components are out of date. While this seems daunting, a peek at the changelog shows that the monthly releases generally aren't massive rewrites, and that it's fairly clear what has been updated. As this is an open source package, a contributor relying on this library can use the material design changelog and the Happy to discuss further and curious to hear what others think - I know this is a bit of a departure from the previous approach, and it does have the definitely disadvantage of being pegged to a "living document" that is not clearly versioned, as well as on relying on the material design changelog. @brad-decker @Nathan-Schwartz @kristajg @danielstclair @BennettStaley @AriLFrankel |
|
I think as long as we keep on top of these changes and have someone own monitoring the material component library we should move forward with always updating to the latest version, but we should definitely record the version that we was current when the component was written at the top of the file. This will help us identify files that are out of date. Thoughs? @martahj |
| a changing spec, please put the following at the top of any files you work in. | ||
|
|
||
| ```js | ||
| // @createdAt DD/MM/YYYY |
There was a problem hiding this comment.
I think i'd prefer the actual version number rather than the date. Version numbers can be viewed via tags in github. Maybe a mixture of @BasedON Version x.x
@updatedAt dd/mm/yyyy
There was a problem hiding this comment.
The date is just to make it easy to track with the material design changelog, I agree it should be the version if we're using the library 👍
There was a problem hiding this comment.
I think both is good, cause you get a sense of the updated date plus the version. I don't think createdAt is required, just updatedAt
|
@brad-decker I think that could work. We could use the (changelog)[https://github.com/material-components/material-components-web/blob/master/CHANGELOG.md] to tell which files changed, and then could update them. How do you see that working with components that did not update in the latest version? Since they didn't update, they would be by default up to both the latest version and the version they were created under. It seems to me that we would want to update the version to indicate that the component is not out of date, but that would create additional work and capacity for mistakes.. thoughts? |
|
@martahj i think with our new direction of using material components as inspiration and not the source of truth makes this not necessary. Thoughts? |
|
@brad-decker If we agree that the process outlined in the changes (using material design's changelog) would be helpful, documenting that we've thought about the versioning issues and have a process in place seems better than not documenting it... but I agree it's not really necessary. |
|
Imo, looking at their changelog for the last few versions, the documented changes seem lower level than would be helpful to map our changes to given our only high level relationship to this library |
|
A lot of it is tangential to what we're trying to do, but some of it is relevant for us trying to stay on top of new features/behaviors and edits - for example without their comment about textfields in April 2017 ("Text fields expands on usage basics and introduces text field boxes for increasing text field discoverability") I don't know how we would learn that we needed to add the text field box feature. |
|
Yes, for sure. I was looking at the changelog of material-components-web not material.io "what's new" This seems like a good thing to keep track of. |
|
I think it would be safe enough to link the changelog in our readme, and make notes in our readme that we are using their library as inspiration. Adding version numbers, etc to files when we aren't going to be holding ourselves strictly to that library seems confusing. So maybe just alter this to remove the notes about versioning and rather commenting/editing to mention the inspiration design source. Also add material.io as inspiration. |
Updates the README to speak to how to handle changing material design
versions.
Resolve #53