Skip to content

Proposal for smooth rolling releases #252

@lrq3000

Description

@lrq3000

As we are receiving more and more issues, we are having more and more PR opened with dormant features that noone is using.

I propose that we integrate these PR into tqdm more quickly and easily than currently, but that we define clear guidelines before.

Essentially, I propose to codify the development process in 2 processes: a solid one for core tqdm, and a way more flexible and lenient for submodules.

Here are my ideas of some release guidelines:

  1. Tqdm core only accepts changes requiring no external module from pure python stdlib and having no or negligible impact on performance. So mostly bugfixes. All changes should be 100% branch covered by unit tests, and commented. Any other kind of change should go in a submodule. Indeed, the core is meant to be rock solid and as fast as a rocket.
  2. Any change to the core's API should be discussed carefully.
  3. Submodules extending tqdm core or any other tqdm module can implement anything, from new experimental features or support for third-party libraries like pandas, numpy, etc.
  4. There is a special development numbering for submodules based on maturity: alpha for experimental code without enough unit test, comment and/or feedback ; beta for well used module with commented code but without enough unit test ; stable for modules with commented code, 80% branch coverage unit tests and enough usage by a userbase (at least 10 users). The status should be written at the top of the class docstring.

To summary, the idea is that we lock the core (like we implicitly do currently but now explicitly with clear guidelines) to maintain the current quality (reliability, performance, API), but still allow new features to be developped quickly: the solution is to use abusively of submodules.

The great thing about submodules is that we don't really care if they are not really stable nor if they are unit tested: they are additional features, people may want to try them or not, it's up to them. But I think we should include them in tqdm public releases, this will allow to get more feedback and provide more quickly the public with new features.

This will also allow us to more quickly develop new features as making unit tests is taking a lot of time, so we can focus on developing new features first, release them, then add unit tests for the popular submodules (instead of adding unit tests for every submodules even the ones that will maybe be removed in the future...).

The other advantage is that we could then more quickly close PR and issues, because currently we have lots of PR that are totally fine but they are not merged because they are not enough unit tested or just not perfect enough by our standards. But I think that our high standards are fine for tqdm core, but not for submodules: submodules are extensions and thus they should have a more flexible development process: add new modules, modify them, delete unused/deprecated ones, refine popular ones (unit test, better code, comments), etc.

In the end, we can rewrite the Readme and add a section about submodules with their respective maturity state and description, for example:

Submodules
-------------

`tqdm` is very extensible, several submodules are provided, with some being stable and some experimental (alpha, beta). Stable modules can be used in production code, experimental modules can change at any time or even be removed.

Here is a list of the available submodules, classified by maturity:

== Stable

=== tqdm_gui
GUI version of tqdm using matplotlib!
... submodule technical documentation here ...

=== tqdm_pandas
Use tqdm to compute/aggregate pandas series and dataframes.
... submodule technical documentation here ...

== Beta
Experimental modules that are routinely used but are not meeting the quality standards to be stable (80% branch coverage unit tests, thoroughly commented code, userbase).

=== tqdm_notebook
Progress bars for your IPython/Jupyter notebook!
... submodule technical documentation here ...

== Alpha
Very experimental modules that may change at any time or even be removed.

=== tqdm_regress
Use machine learning (polynomial regression) to better predict time!
... submodule technical documentation here ...

=== tqdm_custom
Nice fish-like animated bars for ASCII art lovers!
... submodule technical documentation here ...

TODO:

  • Create a file about rolling release guidelines? And/or a wiki page?
  • Merge pythonic submodules architecture Pythonic submodules architecture #198 (else submodules may impact core module, thus this whole guidelines plan can't work).
  • Merge functional PRs.
  • Update Readme with list of submodules.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions