search

LSSTDESC / desc-data-portal

LSST DESC Data Portal web app and the associated documentation and example notebooks.
https://data.lsstdesc.org
BSD 3-Clause "New" or "Revised" License
7 stars 2 forks source link

Document backward-incompatible updates #96

Open yymao opened 1 year ago

yymao commented 1 year ago

The most recent GCRCatalogs release (v1.5.0) introduced some backward-incompatible updates. See https://github.com/LSSTDESC/gcr-catalogs/releases/tag/v1.5.0. While the changes are detailed in GCRCatalogs release page, most users probably won't check that page. I wonder if we should have a place to document backward-incompatible updates on the data portal site, or in the data release note, or both? Thoughts?

heather999 commented 1 year ago

Yes - I think we should do something, maybe both in the note and the portal site.
For the note - should any of the example code snippets be updated or expanded? For backward incompatible changes - is there a way to highlight that on the gcr-catalogs release notes and then point to the changelog from the portal & note and generically inform people that they should check the notes to be aware of the current changes in GCRCatalogs? Or would we want to explicitly call out a select number of changes that we feel are important enough to highlight? I guess I'm trying to see how we can use the GCRCatalogs github repo as the best source of truth, and avoid having to make too many future updates to the portal pages and note to explain changes to the package.

yymao commented 1 year ago

We can certainly link to GCRCatalogs' release page, and we should add this to both the note and the site.

The remaining question then is whether we want to call out specific important changes. I agree that this would result in more updates in the future. I don't feel very strongly either way.

heather999 commented 1 year ago

I'm not inclined to call out changes further here on the data portal or on the note - but maybe we should let Joanne weigh in. She's away from the laptop this week.

While making this update - do we want to address #94 as well?

yymao commented 1 year ago

That's probably a good idea. But I should note that I am currently traveling so my availability is a bit limited at the moment.

JoanneBogart commented 1 year ago

I do think it's useful to highlight specific changes, but would prefer that this also be indicated somehow in the GCRCatalogs repo, in a way that the Data Portal doc (probably including release note) can point to, rather than keeping a separate list elsewhere.