Meta: SEP Versioning #1046
Comments
|
Thanks for creating this discussion. Indeed it's difficult to manage so many changes in SEPs while keeping Anchor and Wallet software compatible across time.
|
I suggested a similar idea a little while ago and one of the pieces of feedback I received was that by moving each new version into a new file we lose the simple ability to view diffs between versions on GitHub. We have the files in Git and I think we should try and leverage them best we can. If we do the changelog idea maybe there's someway we can link in the changelog to each version of the SEP.
We've just started doing this, although we are only referencing SEPs and not their versions. Most SEPs have not been updated yet, but you can see in some like SEP-30 there is a Thoughts? Would this deliver value? Would this be onerous to keep updated? I expect there is a maintenance cost to making sure all SEPs stay updated.
💯 I think this would deliver significant value. If we added a changelog, I think we could include that into the SEP itself as one of the first sections, just under the dependencies. |
I think it's better to have it than not have it (dependencies section). The maintenance would be required, but it's only updated once (ideally) on every version change. It would save time from Anchors and Wallets trying to figure out the incompatibilities themselves. Another idea is for Anchors to list which SEP versions they support, maybe in the |
I really like having a changelog and a link to previous versions! A non-breaking approach to preserve the file structure is linking to the commit where the previous version was updated, something like: Versions
Having a detailed changelog specifying the breaking changes will raise awareness for both SEP editors and industry implementers, there's a lot of upside here!
I like this idea a lot! Most SEPs have a |
|
This issue is stale because it has been open for 30 days with no activity. It will be closed in 30 days unless the stale label is removed. |
|
This issue is stale because it has been open for 30 days with no activity. It will be closed in 30 days unless the stale label is removed. |
|
Another way to solve the SEP document versioning and changelogs is to use the Add/Update/Fix/BreakingChanges sections. For SEP-30, the versions section could look like this: Versionsv0.8.1 (#913) – 2021-05-04:Add
v0.8.0 (#800) – 2021-01-11:Breaking changes
For the SEP document compatibility, we could just add the versioning definition that @leighmcculloch suggested to the document preamble: About how to make the compatibility discoverable by Wallets, I don't think the stellar toml is the best method because not all SEPs need a stellar.toml (SEP-30 for instance doesn't need it), so adding the compatibility info to |
|
+1 for a detailed changelog for each SEP. We could use a directory structure like: However, SEPs are linked everywhere in our documentation and other documents. Changing the file structure will break those links, which I think should be considered before making this change. Another non-breaking change would be This is definitely not as elegant but we could link the changelog in each SEP. I think the Regarding the question of how anchors publish version info about their services, I agree with @marcelosalloum that using |
|
@marcelosalloum I like the changelog idea. I think we can include the changelog in the SEP itself, probably at the bottom in descending order. The expectation being that any change to the SEP includes a new line item in the changelog describing for that version what is being added, removed, deprecated, etc. Having it inside the document helps contain the SEP and everything about it in a single place that increases the chance it gets discovered by readers or updated by authors. I think the |
|
I've opened a PR with a proposal for how this could look: #1110 |
Add a very lightweight changelog section to the SEP template. This idea was suggested by @marcelosalloum in #1046 (comment). SEP documents evolve over time but there is no location where a reader can quickly read in prose a description of what has changed from one version to the next. While the Git history and PR descriptions for changes made to the SEP provide insights it requires a lot of effort for a reader to sift through all that information to find what the final incremental changes are that have been made. Requiring a changelog entry will also help us evaluate the necessity and clarity of a change since the changelog is persisted forever we must choose wisely the changes we make. The changelog @marcelosalloum had proposed was a larger document with sections under each version. After some experimentation I am proposing a more lightweight changelog. The reason being is that version changes in SEPs are often quite different to software releases in that we don't usually queue up changes then issue a release. Instead we issue a release and update a version with every small change we make to a SEP. For this reason I think we need only a single line to briefly state what each versions change is. Since the changelog will grow over time this will also keep it succinct and easy to parse and read. The changelog @marcelosalloum had proposed was a separate markdown document but I've included the changelog in the SEP itself. I think it is very helpful today that most things for a SEP live inside the one SEP document. If the changelog is at the end it is unlikely to get in the way of the document content. It is easier to discover as well if it is embedded.
|
This issue is stale because it has been open for 30 days with no activity. It will be closed in 30 days unless the stale label is removed. |
Over the last couple years a few folks have pointed out that SEP versioning needs some work.
Unlike CAPs, SEPs are not a point-in-time proposal. SEPs are protocols and specifications that are improved over time. This means that changes are made to them over long periods of time, sometimes bug fixes, sometimes improvements or new features, and sometimes breaking changes where necessary.
All SEPs have a
Versionmeta field in their preamble. The SEP README provides instructions on how versions should be assigned during the draft stage (i.e.v0.X.Y) and in the Active and other stages (i.e.vMAJOR.MINOR.PATCH).That is the extent of the support structures for versioning SEPs. SEPs do not typically provide a way for implementers to support multiple incompatible versions at the same time if a breaking change has occurred, or to communicate with another party about what version they support.
This issue is a place where we can discuss these and other problems relating to SEP versionins, and discuss ways we could improve.
cc @rice2000 @JakeUrban @tomerweller @accordeiro @marcelosalloum @yuriescl
The text was updated successfully, but these errors were encountered: