Proposal for smooth rolling releases

[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.

[lrq3000]

What do you think about it guys? Please feedback!

[casperdcl]

Hmm I haven't really read or thought about this in detail yet, but I'd like
to add that core tqdm should be by default optimised to be as fast as
possible for specifically exactly this loop:

for _ in trange(int(1e8), desc="hello"):
pass

That is, no inner computation (extreme case of low inner computations), a
relatively high number of loops, and no additional arguments apart from a
description and possibly unit.

On 28 August 2016 at 18:03, Stephen L. notifications@github.com wrote:

What do you think about it guys? Please feedback!

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#252 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AKR9m4YK6ny8cOSZ729b9BD3MtdnsZv7ks5qkb9MgaJpZM4Ju929
.

[lrq3000]

Agree @casperdcl but I would add another benchmark as mandatory:

for _ in trange(int(1e5), mininterval=0, miniters=1):
  pass

Just to have the other extreme case.

Also, is there a reason desc="hello" is necessary?

[CrazyPython]

@lrq3000 I agree 100%. But extensions to tqdm core can still be accepted, as subclasses of tqdm. The best of both worlds!

Encourage those using unstable submodules to use tqdm== instead of tqdm>=.

[CrazyPython]

My proposed suggestion would let people use and add performance slowing features without affecting core performance.

[lrq3000]

@CrazyPython Yes exactly that's the point, let's be more lenient about merging in submodules that are slower or using third-party libraries. Until now we refused because we wanted high quality submodules, but we can make a clear classification system (alpha, beta, stable) so that users know which submodules they can use in production and which are more experimental.

[chengs]

Very nice!