Skip to content

doc: announce 1.0.0 stable release #1706

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Dec 10, 2021
Merged

doc: announce 1.0.0 stable release #1706

merged 1 commit into from
Dec 10, 2021

Conversation

lukpueh
Copy link
Member

@lukpueh lukpueh commented Dec 3, 2021 •
edited
Loading

Fixes #1676

Description of the changes being introduced by the pull request:

  • Add a document that announces a stable "modern implementation"-only 1.0.0 release, with the following contents:

    • the scheduled release date
    • contents of release (metadata API, ngclient, no legacy code)
    • legacy code deprecation note (adr 2)
    • note about lack of repository tool (adr 10)
    • migration instructions

  • Add "important notice" to head of main README, pointing to above document.

Please verify and check that the pull request fulfills the following
requirements:

  • The code follows the Code Style Guidelines
  • Tests have been added for the bug fix or new feature
  • Docs have been added for the bug fix or new feature

@lukpueh lukpueh marked this pull request as draft December 3, 2021 08:41
@coveralls
Copy link

coveralls commented Dec 3, 2021 •
edited
Loading

Pull Request Test Coverage Report for Build 1562796762

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

Details

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage increased (+1.0%) to 98.562%
Totals Coverage Status
Change from base Build 1562780344: 1.0%
Covered Lines: 3931
Relevant Lines: 3958
💛 - Coveralls

@lukpueh lukpueh force-pushed the 1.0.0-announcement branch from c408549 to 8f458a1 Compare December 6, 2021 10:26
kairoaraujo
kairoaraujo reviewed Dec 6, 2021
View reviewed changes
Copy link
Contributor

@kairoaraujo kairoaraujo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, my comment might be a wrong point of view, but I would like to share🙂

README.md
is scheduled for January 2022. Please see the [*1.0.0
announcement*](1.0.0-ANNOUNCEMENT.md) page for more details about the release
and the deprecation of the legacy implementation, including migration
instructions.*
Copy link
Contributor

@kairoaraujo kairoaraujo Dec 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

migration instructions

IMO, It sounds like we have a kind of documentation explaining how to migrate from current version to 1.0.0.

Not sure if expressing as "migration instructions" fits here. That sounds more when you have a software/product/service and transparent steps to migrate, avoiding issues during this process.

We are deprecating the client.py and repo.py, and we don't have a kind of migration instructions for it. We provide a new repository API and a new powerful Updater library to implement the new repository and client tool.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the idea here is that we want our current users using the old client and repository API to eventually migrate to the new code.
We already have a working ngclient, but using the new repository API will require more decisions to be made by the users and that's why he focuses on that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kairoaraujo, I agree that the section at the bottom of the new document, which I'm referencing here, is not a migration guide in the strict sense and as you describe it, but it is a set of instructions that should help users to migrate from pre-1.0.0 to 1.0.0. I suggest we leave it for the lack of a better term, unless someone has a good idea.

MVrachev
MVrachev reviewed Dec 6, 2021
View reviewed changes
1.0.0-ANNOUNCEMENT.md
Comment on lines +26 to +27
*metadata API* makes it easy to replicate the desired functionality tailored to
the specific needs of any given repository (see *Migration* for details).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if we are citing ADR10 then maybe we should mention something about the Minimal repository abstraction and tiny repository API that will be provided?

Copy link
Member

@jku jku Dec 7, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't think they'll be available (or at least not stable) by 1.0.0 so talking about them might be premature. But maybe it would make sense to mention that we do plan to offer more on the repository side soon, just not quite in 1.0.0

(this is in response to the earlier comments)

jku
jku approved these changes Dec 7, 2021
View reviewed changes
Copy link
Member

@jku jku left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks fine to me. I wonder if "announce" gives a wrong impression -- on the other hand something like "roadmap to 1.0.0" does not sound as committed so maybe this is a better choice :)

1.0.0-ANNOUNCEMENT.md
Comment on lines +26 to +27
*metadata API* makes it easy to replicate the desired functionality tailored to
the specific needs of any given repository (see *Migration* for details).
Copy link
Member

@jku jku Dec 7, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't think they'll be available (or at least not stable) by 1.0.0 so talking about them might be premature. But maybe it would make sense to mention that we do plan to offer more on the repository side soon, just not quite in 1.0.0

(this is in response to the earlier comments)

@lukpueh
Copy link
Member Author

lukpueh commented Dec 7, 2021

I wonder if "announce" gives a wrong impression

I struggled quite a bit with the name of the document and its title. "Announce" indeed sounds a bit like it is already this release, and "roadmap" sounds a bit too far away. I also considered "Towards 1.0.0" as title, but that has a similar problem as "roadmap". I suggest we leave "announce" and hope that the rest of the document makes it clear enough.

lukpueh
lukpueh commented Dec 7, 2021
View reviewed changes
@lukpueh lukpueh marked this pull request as ready for review December 10, 2021 09:34
@lukpueh
doc: announce 1.0.0 stable release
d06ca61 
* Add a document that announces a stable "modern
  implementation"-only 1.0.0 release, with the following contents:
  - the scheduled release date
  - contents of release (metadata API, ngclient, no legacy code)
  - legacy code deprecation note (adr 2)
  - note about lack of repository tool (adr 10)
  - migration instructions

* Add "important notice" to head of main README, pointing to above
  document.

Signed-off-by: Lukas Puehringer <[email protected]>
@lukpueh
Copy link
Member Author

lukpueh commented Dec 10, 2021

Many thanks for the reviews, @kairoaraujo, @MVrachev and @jku! The blocking PRs have been merged and I:

  • made sure that the link to ADR 10 still works,
  • added the patch to show that we are working on a repository tool replacement, and
  • will ignore our collective reservation towards the terms "migration" and "announcement" in this context, as we agreed in our last conversation.

Merging when CI/CD returns...

@lukpueh lukpueh merged commit bc21225 into theupdateframework:develop Dec 10, 2021
@lukpueh lukpueh mentioned this pull request Dec 13, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kairoaraujo kairoaraujo kairoaraujo left review comments

@MVrachev MVrachev MVrachev left review comments

@jku jku jku approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Add 1.0.0 announcement / migration help
5 participants
@lukpueh @coveralls @jku @kairoaraujo @MVrachev