Changelog

[matteosantama]

We need to track changes and publish a changelog

[junziz]

Looks like we already have the latest version of the doc pointing to the newest master branch while "stable" version pointing to the released version, which is good! But apart from the changelog, let's also try to

• 1. have a doc version for each release, and label the stable and latest as e.g., 0.1.1 (stable) and 1.0 (latest) (or 1.0 (beta), 1.0 (dev), etc.), or at least mention clearly the versions on the index page;
• 2. mention in the GitHub README.md the current stable/last released version and the dev/latest/beta version that is to be released where the master branch is for, and remind the users to look for the corresponding doc versions (especially those who check out GitHub master branch locally should refer to the latest/dev/beta doc);
• 3. make MFGLib available on anaconda if that is not very difficult (but if it is then no need).

Thanks!

[matteosantama]

There might be a confusion about "stable" versus "latest". "stable" points to the most recently published package version, while "latest" points to the codebase as it currently exists on main. You can think of "latest" as "dev".

readthedocs provides several add-ons that deliver (most) of the features you mention.

1. The flyout menu: See an example here. Users very clearly see all the available documentation versions.
2. Non-stable notification: "A notification on all non-stable versions is shown to clearly communicate to readers they may be reading an outdated version of the documentation. Specifically, when a version is being shown that is not the stable version, and there is a stable version available."
3. Latest version notification: "A notification shown on the latest version tells readers they are reading the latest/development version of the documentation that may include features not yet deployed. Specifically, when the latest version is being shown, and there’s also an active stable version that is not hidden."

If you're happy with those configurations, I will go ahead and get them implemented. I can also update the README to describe the difference between "stable" and "latest" so there is no confusion for our users.

I created a separate issue for the Anaconda package. We can discuss further in #49.

[junziz]

There might be a confusion about "stable" versus "latest". "stable" points to the most recently published package version, while "latest" points to the codebase as it currently exists on main. You can think of "latest" as "dev".

Yeah that's why I said 0.1.1 (stable) and 1.0 (latest) as 0.1.1 is our latest release, while 1.0 (not yet really released or even just formally defined) is the current main/master branch that is not released yet. So I thought we are understanding these the same way, no?

And all three features you mentioned are great but iiuc they are already implemented in our doc website, no? At least 1 and 3 are definitely already implemented I think. For 2, we currently only show stable/latest and no specific list of versions (like in the flyout menu example you shared). Let's list those as well. Was just thinking that it would be nice if we can clearly state that the "stable" version is 0.1.1 while the "latest" version is (going to be) 1.0(.0). Just similar to what pandas website does (cf. the top right bar of dev, 2.2 (stable), 2.1, etc. https://pandas.pydata.org/docs/dev/index.html). Not something really significant anyway so anything not straightforward to support we can just ignore for now :)

can also update the README to describe the difference between "stable" and "latest" so there is no confusion for our users.

Yes let's do that :) Mainly just so that the readers know that if they checkout the repo directly instead of pip install, etc. they would get "latest" instead of "stable".

created a separate issue for the Anaconda package. We can discuss further in https://github.com/radar-research-lab/MFGLib/issues/49.

Sounds good!