Stable tagged release?

[bradyrx]

It would be great if you could make a tagged version release on pip that's stable. The API changes so frequently right now that I feel like I'm rewriting my notebook cells every week when I pull down updates. Then folks could just install a specific version from pip while you continue development.

Releasing on PyPI takes < 5 minutes: https://github.com/bradyrx/climpred/blob/master/HOWTORELEASE.rst. You could tag a v1.0.0 and then follow semantic versioning (https://semver.org/) as you release more features.

[lukelbd]

My apologies. I probably should have submitted tagged releases with deprecation warnings, etc., but (1) I didn't like the idea of "releasing ProPlot to the world" without setting up CI testing, and (2) I didn't want to document versions of ProPlot before the new "panels" API is complete (see below), since it's such a big change.

Rest assured after the panels API is finished, the next priority will be CI testing and the version 1.0 release -- I've had your climpy instructions open in a tab. Then minor latitude/longitude gridlines will be a good 1.1 task. If there are future backwards incompatible changes, they will be more incremental, and will be implemented with warnings, appropriate version changes, etc.

Just to give an explanation for the two big changes you've noticed:

1. Instead of xlines, ylines, etc. for ProjectionAxes.format, it is now lonlines, latlines, etc. -- this was changed because of course, for some map projections, longitude lines might be perpendicular to the y axis and latitude lines perpendicular to the x axis, and because I didn't want to support so many extra keyword args.

   I also wanted to make ProjectionAxes.format consistent with PolarAxes.format, which now uses r and theta instead of x and y (e.g. rlim, thetalim, thetaticks, etc.).

2. Instead of having to specify "panels" in the subplots() call, you now generate panels and "fill" them with colorbars and legends on-the-fly. I recently realized the concept of "panels" is baffling and cumbersome for new users, so I've been trying to make the process of putting colorbars/legends on the side of an axes more natural.

   I'm sure you'll agree that

   f, ax = plot.subplots()
   ax.pcolormesh(data, colorbar='r')

   and

   f, ax = plot.subplots()
   m = ax.pcolormesh(data)
   ax.colorbar(m, loc='r')

   are cleaner and more intuitive than

   f, ax = plot.subplots(axcolorbar='r')
   m = ax.pcolormesh(data)
   ax.rpanel.colorbar(m)

   In the next version, you will no longer be able to manually "fill panels" with a colorbar or legend. "Filling panels" will just be something that just happens under-the-hood when you specify e.g. legend(loc='r') or colorbar(loc='r'). The next version will also support arbitrarily stacked panels -- for example, if you call ax.colorbar(loc='r') twice, it generates two stacked colorbars on the right hand side.

   And if you want to plot stuff inside panels, since this is pretty rare, you generate them just like you generate inset axes:

   f, axs = plot.subplots()
   paxs = axs.panel_axes('r', width=width, space=space, ...) # analogous to axs.inset_axes()
   # paxs = axs.panel('r') # also works

   This means I will remove the leftpanel, rightpanel, etc. axes attributes, remove the panel, axpanels, etc. keyword args from the subplots() function, and condense the "Panels" section of the documentation and move it to "Introduction".

[bradyrx]

No worries! Didn't mean to come off harsh there. I love the package and want to keep using it so keeping a stable version installed will help me to flow with it. I noticed the panels change, and after I went through the docs, it's a nice logical change.

I can tell you CI is going to take a long time to set up with regards to decent coverage on testing. I would help with the testing but am getting pulled in too many directions with my work right now. But you could probably cover a lot of your modules just by having testing to generate various configurations of panels, plots, etc. Looping through map projections and so on (see test_perfect_model_prediction.py in the link below for pytest parameterizations to loop through a bunch of features/keywords). So it depends on how motivated you are, but I'd rather see a v1 release sooner with no testing than wait til you get full testing coverage, IMO.

Here's our testing suite at climpred: https://github.com/bradyrx/climpred/tree/master/climpred/tests

A barebones test at my personal package esm_analysis: https://github.com/bradyrx/esm_analysis/tree/master/esm_analysis/tests

The most helpful thing you could do for users is to maintain a changelog with your updates: https://github.com/bradyrx/climpred/blob/master/CHANGELOG.rst. Then we can just jump right there with the new releases and see that the panels API changed and so on. That of course would require you to have contained Pull Requests :)

As always, feel free to email/text if you have questions about the CI stuff. Once you get into the flow I'm sure it'll be smooth sailing for you.

[lukelbd]

I am now thinking I will release a version 0.1 after #47 is merged but before the two major refactoring PRs are merged (#50 and #45). I'll consider the 0.X releases "beta" versions (there might just be one or two), then when those PRs are merged, I will jump up to 1.0 and go from there.

This project is getting more stars every week which is cool but kind of scary. It's definitely time for people to be able to download individual stable versions. After this you will also be able to contribute directly if you feel so inclined :).

It looks like matplotlib has an image comparison utility that they use for their tests, so that might be a starting point for failures that are "visual/subjective" in nature. I suppose I'll add tests incrementally within the version 0.X releases.

[lukelbd]

Closed by 9280232. See the new README and the pypi page. Documentation is not up because of an RTD memory issue, but once they respond to readthedocs/readthedocs.org#6412 it will have pages with contribution instructions, release instructions, etc. like xarray and climpred.

[bradyrx]

readthedocs doesn't give you much memory at all to build. I had memory crashes just by having matplotlib as a dependency for my docs I believe. So for now I just pre-run the notebooks and don't have nbsphinx execute them, which unfortunately defeats the purpose of having nbsphinx for testing.

@xylar had the same issue at MPAS-Analysis (MPAS-Dev/MPAS-Analysis#652) and opted to just host their docs on github pages, which is another option. Here's their Travis code to build and publish the docs: https://github.com/MPAS-Dev/MPAS-Analysis/blob/develop/ci/test_and_publish_docs.bash

Note that as I mentioned in another PR or issue, you can get RTD to build on your PRs now with a simple email. Then you'll be able to catch before merging if they break like this.

[lukelbd]

That's too bad. Not sure if you're aware of nbstripout but you could use this in your travis build instructions. I currently use nbstripout as a gitattributes filter so that cell output is never committed (see HOWTOCONTRIBUTE (which was mostly copied from yours), .gitattributes, and .gitconfig). This massively reduces the repo size.

This guy on stackoverflow has another interesting approach. I kind of prefer keeping things on readthedocs because it lends the project more credibility... a readthedocs URL seems more "official" than some random dude's lukelbd.github.io URL (guessing that's partly why you haven't switched to gh-pages?). I'd have to migrate the project to a shared Github account like proplot/proplot so it shows up as proplot.github.io/proplot, but that's annoyingly redundant. Turns out you cannot configure gh-pages to publish as projectname.github.io, the only other way would be to buy a URL.

First step I think will be to formally request more memory. They have instructions to do so here. I have pretty good reason to need more memory since it's a plotting package. If that fails may try that stackoverflow approach... I like the idea of putting figures in a submodule because that keeps the core repo size small.

I emailed them to opt-in to RTD integration, just waiting on a response. When that happens (assuming they increase my memory) I guess I'll remove the make html step from Travis. Sidenote, currently Travis just tests the notebooks, but at some point I'll (1) install pre-commit autopep8 hooks like IIRC you use for climpred, and maybe black too, and (2) have Travis run the flake8 checker.

[lukelbd]

Decided to set up pre-commits and add flake8 to travis today... pre-commit is pretty darn awesome, thanks for pointing it out. My code is also now pep8-compliant; autopep8 -i -a *.py was a big help.

[bradyrx]

That's too bad. Not sure if you're aware of nbstripout but you could use this in your travis build instructions. I currently use nbstripout as a gitattributes filter so that cell output is never committed (see HOWTOCONTRIBUTE (which was mostly copied from yours), .gitattributes, and .gitconfig). This massively reduces the repo size.

But doesn't this in turn wipe out all the output of the cells? Most of my notebooks have meaningful cell output (e.g. xarray dataset printouts, figures) that I want on my docs. So I need to keep the cells executed if I am not having nbsphinx do the job. Or am I missing the point on what nbstripout does?

This guy on stackoverflow has another interesting approach. I kind of prefer keeping things on readthedocs because it lends the project more credibility... a readthedocs URL seems more "official" than some random dude's lukelbd.github.io URL (guessing that's partly why you haven't switched to gh-pages?). I'd have to migrate the project to a shared Github account like proplot/proplot so it shows up as proplot.github.io/proplot, but that's annoyingly redundant. Turns out you cannot configure gh-pages to publish as projectname.github.io, the only other way would be to buy a URL.

First step I think will be to formally request more memory. They have instructions to do so here. I have pretty good reason to need more memory since it's a plotting package. If that fails may try that stackoverflow approach... I like the idea of putting figures in a submodule because that keeps the core repo size small.

Keep me posted here on what happens. Particularly if they respond well to a memory increase. I don't fully understand what they're doing on the stack exchange example, and I currently like at least that things are all handled through Travis and RTD PR beta addon.

Decided to set up pre-commits and add flake8 to travis today... pre-commit is pretty darn awesome, thanks for pointing it out. My code is also now pep8-compliant; autopep8 -i -a *.py was a big help.

Awesome. This is a huge help overall for development.

[lukelbd]

Right so nbstripout is just a command-line utility. You can use it as a gitattributes filter but you could also do something like adding nbstripout docs/*.ipynb before make html in your .travis.yml, then nbsphinx will run/check every cell during make html. That's all I was saying.

FYI when you use nbstripout as a gitattributes filter, it strips what git "sees", not what is actually on your disk. The filter is applied during staging, i.e. git add, and when "loading" stuff from the git version control, e.g. git checkout. So you can have all your cells and stuff compiled on your local machine and make commits, and the output won't be stripped until you checkout something or have to merge changes to the notebook from another branch.

...or I guess you can just set nbsphinx_execute = True.