search

executablebooks / meta

A community dedicated to supporting tools for technical and scientific communication and interactive computing
https://executablebooks.org
129 stars 166 forks source link

Discussion for beta release #48

Closed choldgraf closed 3 years ago

choldgraf commented 4 years ago

Originally in https://github.com/executablebooks/meta/issues/44, moving here so we can keep track of it:

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

choldgraf commented 4 years ago

Finished PDF output! https://github.com/ExecutableBookProject/sphinx-book-theme/pull/22

choldgraf commented 4 years ago

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 commented 4 years ago

Two minor issues worth mentioning in a release readme:

https://github.com/ExecutableBookProject/MyST-NB/issues/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: https://github.com/ExecutableBookProject/MyST-NB/issues/126 --(the second align environment at https://phaustin.github.io/MyST-NB/equno.html )

chrisjsewell commented 4 years ago

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

with ExecutableBookProject/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 commented 4 years ago

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:

chrisjsewell commented 4 years ago

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:

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

choldgraf commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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: image

choldgraf commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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. https://github.com/executablebooks/MyST-NB/issues/129 is probably not, because it won't apply if people are building with jupyter-book).

jstac commented 4 years ago

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 commented 4 years ago

I think there are 2 main blocks:

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

cheers @choldgraf, sounds good to me

choldgraf commented 3 years ago

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