search

MDAnalysis / UserGuide

User Guide for MDAnalysis
https://userguide.mdanalysis.org
22 stars 35 forks source link

decouple User Guide releases from MDAnalysis library releases #373

Closed orbeckst closed 3 months ago

orbeckst commented 3 months ago

Is your feature request related to a problem? Please describe. The User Guide is versioned like the core MDAnalysis library and User Guide releases are synchronized with core lib releases. However, this means that changes and fixes to the User Guide have to wait until the core lib releases. Most fixes to the UG are not directly related to the core lib so we are needlessly holding them up from appearing in the stable release of the UG.

Describe the solution you'd like I would like to make User Guide releases independently from the core library so that we can push out a new stable release whenever we think it makes sense.

I am not 100% sure how we would want to handle versioning. I think it still makes sense to carry the major release of current MDA, but I don't think we need to follow minor releases. Ultimately, MAJOR.MINOR maybe just sufficient for the UG.

Describe alternatives you've considered Do nothing. Point people to the dev version of the UG.

orbeckst commented 3 months ago

My rationale is really that User Guide and core library are not being kept in sync by us anyway so why are we artificially restricting ourselves in releasing a new version of the UG when we want to? Or why do we need to release a new version of the UG with a new core lib release even if nothing changed in the UG?

IAlibay commented 3 months ago

I disagree with this, or at least partially.

I don't have the capacity to do a full explanation yet so I'll come back with more details later. Short term: the UG stable version is built against the latest stable version of MDA, which means that it reflects the contents of the current release (this includes anything in the auto-generated tables that are created from MDA core library contents).

The reason we release a new version of the UG when we release a new version of the core library, even when the UG hasn't been updated, is to make sure any auto-generated content is up to date.

A separate, and possibly more important, point is that the user guide is where folks go to get information about a given release (people don't work off develop), so the UG being out of minor version sync is a problem.

A possible compromise: don't sync on bugfix version, then you can make more releases of the user guide. Although honestly you could also just re-release the user guide on the same version number if necessary.

A possible caveat to having more releases of the UG: big artifacts - the more versions you have the faster we get to a point where the UG won't deploy because we're uploading too much data.

orbeckst commented 3 months ago

The fact that we are auto-generating content in the UG convinces me that we have to keep it in sync.

I'd avoid the confusion with patch-level numbers being out of sync so I'd then stick with the rigid coupling.

The big artifacts need to be addresses one way or the other... maybe prune older versions? But that's a different issue...

I am going to close as "won't fix".