Discussion for beta release

[choldgraf]

Originally in #44, moving here so we can keep track of it:

TO-DO LIST MOVED TO: https://github.com/orgs/executablebooks/projects/1

[choldgraf]

Finished PDF output! executablebooks/sphinx-book-theme#22

[choldgraf]

Hey all - I think that we are pretty close on this. The main remaining items are discussions around API, documentation, etc. Do we have any major changes we want to make there? Or is it good enough for a "beta" release to collaborators? I am kind-of itching to get this stuff out in the wild :-)

[phaustin]

Two minor issues worth mentioning in a release readme:

executablebooks/MyST-NB#129 might cause confusion among users writing their own build scripts for MyST-NB.

Also for MyST-NB -- at least for me, environments without $$ delimiters still don't seem to be being handled by mathjax with current master: executablebooks/MyST-NB#126 --(the second align environment at https://phaustin.github.io/MyST-NB/equno.html )

[chrisjsewell]

Yeh its mainly there, you know best the state of ExecutableBookProject/cli, then the main potentially "blocking" issues on MyST-NB are:

• Execution timeout MyST-NB#139
• Handling unwanted execution artefacts + folders MyST-NB#122
• mispecifying _build directory causes jupyter_execute recursion MyST-NB#129

with executablebooks/MyST-NB#126 maybe not blocking but something that needs to be looked into a bit more.

I've obviously got a few other things going on these days 😬 So can't promise I'll close these in the immediate future. In that case don't let them stop you from starting to (tentatively) start rolling this out

[choldgraf]

looking through these issues, I think that we are in pretty good shape to have a "friends and family" style beta release. What if we did:

• Move the CLI to a jupyter-book "beta" branch
• Make a "beta" release of jupyter book from that branch
• Add a note to the documentation that a beta is coming, with a link to the page, but don't make it a strong call to action
• We start telling our power-user collaborators that they should try out the beta and give their feedback. Warn them that things might be rickety or might change.
• We open a github issue for feedback from people, that includes a "todo" list of things people have brought up (including items in this issue that don't get finished)

[chrisjsewell]

Hey guys, hope all is well. As mentioned before, I have my AiiDA day job now, so won't be quite as active on this at the moment! But if we want to have a little catch-up Zoom at some point, I'm sure I can free up the time 😁

One thing that I wanted to quickly mention, from my recent experience are project boards. With the amount of issues on repositories stacking up (which I'm sure will be getting even longer after the beta release!) these are quite handy for organising/grouping issues across repositories.
I've made an example one here for the beta release/final, which you might consider adding to:

• https://github.com/orgs/ExecutableBookProject/projects/1
• https://github.com/orgs/ExecutableBookProject/projects/2

Also, this is a good example of their use: https://github.com/aiidateam/aiida-core/projects

[choldgraf]

I am all about project boards, +1 on using them if y'all are willing and interested. Agreed that is a better way of keeping track of milestones and issues needed for them

[choldgraf]

I'm gonna close this so that we use the project board and don't de-duplicate information. @chrisjsewell I believe that you added your items above to the board...I also added the missing pieces from the list at the top of this issue, but feel free to add more if I missed something

[choldgraf]

Actually, I take it back...maybe instead I will re-brand this issue to "Discussion for beta release" and we can use this for conversation around the items that are in the project. That work?

[chrisjsewell]

Yeh it's a shame that there is no discussion tab in the project board. The other option that I've just messed around with is https://github.com/orgs/ExecutableBookProject/teams/ebpteam/discussions, although I don't know if there's any extra benefit to using this.

BTW if you create your own Project Board, its usually best to select this template:

[choldgraf]

Hey all - just a heartbeat on the beta release items:

https://github.com/orgs/executablebooks/projects/1

I am curious what @chrisjsewell meant for "beta release" in the context of that project board. Did you imagine "there will be no beta release until these things are done"? Or did you just mean this for a general to-do list across repositories while the EBP is in "beta" state?

The reason I ask is that I'd like to "announce" the re-write of Jupyter Book and release v0.7.0 out of pre-release status (particularly because now the docs are updated). However I'm not sure if you didn't want any "beta" release happening until all those issues are tackled. (and to that point, I'm a bit concerned that those issues will take some time to tackle...)

[chrisjsewell]

Yes that was the intent.
The math task is more of an enhancement (although can lead to a bug with the current mathjax config), so could be pushed back to a “beta-2”.
The other 4 though are literal bugs; so if you do release now, you will being releasing code that is known to be faulty.
I’ll leave that to your discretion though, if you thing the timing outweighs the quality control 😬

[choldgraf]

I agree about shipping buggy code - but I think for some of them they are only "bugs" if they are officially supported features :-) for example, I think it could be reasonable to just say "this version of jupyter book doesn't support ipywidgets", rather than to block the release of it while we wait for somebody to figure out that nbclient / nbconvert bug.

So my take is that of the main items in that list, the important ones to fix are the "basic" usage bugs in MyST-NB and jupyter-cache.

Stuff that seems like it could be in the next beta is the Math stuff, and Ipywidgets + nbclient bug (and we could say "widgets are not supported", note I also found this bug)

do you agree? (and if so, I can move around the cards)

[choldgraf]

Another 🔥 under out butts: this tool is in development and will be released sometime in the soon-ish future: http://book.d2l.ai/index.html

It is a Sphinx-based book generation tool that lets you write in extended markdown and supports jupyter notebook execution.....

I'm gonna take another look at the project board and try to pick out the cards that should really be blockers for us (e.g. executablebooks/MyST-NB#129 is probably not, because it won't apply if people are building with jupyter-book).

[jstac]

Damn, that really is close to what we're doing! @chrisjsewell, do you have time to help clear up some of those "literal bugs"? (My inbox got flooded with GH notifications and I stopped watching some repos, so I'm not up to speed on what's happening with them.)

[choldgraf]

I think there are 2 main blocks:

• MyST-NB execution error. I just opened a PR here: fixing myst nb execution bug MyST-NB#175
• jupyter-cache artifacts error. I opened up a PR that I invite somebody else to finish here: skipping artifact paths jupyter-cache#49

The others (IMO) are less-concerning because they are less-likely to happen with Jupyter Book (and that's the "beta" we're talking about), or they're more like enhancements rather than features.

IMO if we can get both of those fixed, then we can make a release on each of our projects, bump jupyter book to v0.7.0 and release a blog post telling people to try it out (with the caveat that it's still in beta so there may be bugs)

[chrisjsewell]

@chrisjsewell, do you have time to help clear up some of those "literal bugs"

Err, super busy at the moment. executablebooks/MyST-NB#175 looks fine and I'll try and have a look at executablebooks/jupyter-cache#49 on the weekend

[choldgraf]

Hey all - just FYI I just released v0.7.0 of jupyter book, which is the new version that we've had under pre-release for about 1.5 months now. I decided to release it because a lot of users were installing the pre-release incorrectly, and it was starting to cause confusion and maintenance burden. I think we should hold off "announcing" the new jupyter book via blog posts until we have all of the issues tackled, though I believe the only remaining issue from our original list is the one about unwanted artifact paths: https://github.com/orgs/executablebooks/projects/1

[chrisjsewell]

cheers @choldgraf, sounds good to me

[choldgraf]

closing this issue since I think it's addressed and we've made a few Jupyter Book releases since then :-)