Extend versions' states

[humitos]

Currently we have active and non-active versions' states.

I suggested more states like inactive and deprecated so they are still being served or shown in the flyout as needed.

I'm creating this issue here to tack this since the #4001 won't cover these new states for now.

[stsewd]

What would be the difference between "inactiva" and "deprecated"? Or are you talking about one state here? Maybe "hidden" is a better name?

[agjohnson]

"hidden" or "archived" are pretty clear adjectives for these versions. Seems we could have the following fields on the version model:

• active = True or False -- is the version going to build again?
• archived = True or False -- is the version archived?
• maybe deprecated = True or False -- is the version not recommended for use?

I think all the possible combinations make sense in this case. Even if a version is active = False, the user can still communicate that it is archived, archived and deprecated, or just deprecated and never built again.

[humitos]

@agjohnson I'm not following you exactly.

Although the adjectives are clear, I'm not sure to understand how they behaves on our platform:

• archived won't be shown in the flyout menu and won't be served
• deprecated won't be shown in the flyout but it will be served when hitting the URL

Combining these, archived=True and active=True is the only state that does not make too much sense since we will be building a Version that won't be served at all.

On the other hand, deprecated=True and active=True makes sense, since although the version is not more supported, a typo or a note or similar could always be added and it needs to be updated (re-built).

The workflow that I see here would be:

1. the version is active=False originally
2. make it public, active=True
3. it gets deprecated=True after years
4. fix a typo on it and re-build automatically
5. after some months/years more it's not supported anymore and want to remove it from the public list of docs, marked as archived=True
   • this action will probably mark the version as active=False also
   • will remove artifacts for this version

[agjohnson]

I think part of the confusion comes from our weird version states currently. We currently have the following 3 states but only talk about 2 to users:

• active -- version builds. version is hosted
• inactive -- version doesn't build. version is still hosted because we have files on disk
• ?? -- the third state is where the version is inactive and finally is not still hosted. users need a way to select into this and can only do this by wiping the version

So this probably dictates we need the following states (let's set aside the discussion of whether these are individual model attributes for now):

• active -- whether the version is building
• live -- whether the version is hosted
• hidden -- whether the version shows up in various reader user menus
• deprecated -- whether the version will show a deprecation warning (this one would probably be an optional addition later, and really only kicks off a sphinx extension that shows the deprecation warning)

So deprecated doesn't affect whether the version is hosted, neither does hidden/archived. Also, I don't think we should enforce deprecated as a mechanism for hiding as there is a very specific meaning behind deprecated -- "this version is not supported".

What do you think about these states? Do these version states help with UX around versions?

[humitos]

What do you think about these states? Do these version states help with UX around versions?

I like these states. hidden is clearer than archived to me, though.

I'm 👍 on going forward with them.

[agjohnson]

Cool. I'm not sure exactly how these attributes are structured yet, as there are some competing values there perhaps. Like, any value of hidden doesn't make sense when we have live=False.

Any opinions here?

[humitos]

Like, any value of hidden doesn't make sense when we have live=False.

In my mind hidden takes preference over live when hidden=True. The other case, live takes preference over hidden when live=False. I don't think it's a problem.

[agjohnson]

Sure, but if there is conflict in how these fields are used, they should be grouped under a single choice field, not necessarily all boolean attributes.

For instance, using the above as an example, if live and hidden result in overlapping outcomes, it doesn't make sense to treat these two attributes as separate boolean fields. They should be grouped under a single choice field so that it's not a question of which boolean field takes precedence. We need to figure out these overlaps in meaning still.

So far I think we've only seriously considered active=True and hidden=True. These two don't seem like conflicting options.

[agjohnson]

We should probably prioritize finishing this and having some functionality for hiding versions however. Users currently don't have any way to accomplish this other than deactivating a version.

[stsewd]

So, hidden is implemented. live sounds like the same as built for me. Not sure about the deprecated state, looks the same as hidden but only with the deprecated banner. Maybe we could just mark hidden versions as deprecated or something like that.

[stsewd]

Any thoughts if this should be considered valid now?

[agjohnson]

I was most interested in hidden, I don't have strong opinions about the others and would aggress that it sounds like there is some redundant meanings there. Deprecated might be a nice dedicated attribute to have, but likely requires we do something special with deprecated versions in a consistent way. Currently, it might only feed into the sphinx deprecated extension, and wouldn't work for other tools. We could revisit this later if we come up with a plan for other version states i think