search

vexflow / vexflow

TypeScript library for rendering music notation & guitar tablature.
Other
63 stars 11 forks source link

Vexflow 5 release plan #224

Open ronyeh opened 4 months ago

ronyeh commented 4 months ago

Let's make a concrete plan to get 5.0 released.

The previous discussion was at #13.

ronyeh commented 4 months ago

I propose for version 5.0:

5.0 will have API differences from 4.x. That's ok. We can improve backwards compatibility as we move forward to 5.1, 5.2, ...as the need arises.

For 5.1:

For 5.2:

For 5.3:

I propose this approach because these are the users most interested in and invested in VexFlow. Let's make our users happy.

ronyeh commented 4 months ago

@rvilarl regarding API docs:

Yes we should generate them. They should be stored in versioned directories in the vexflow-docs repository.

So the directory structure could be:

vexflow-docs/
  ver/
    5.0.0/
    5.1.0/
    ...
  2024/
    0724-f8b49c2/
    0816-97da26e/
    ...

This allows us to manually generate the API docs for releases, or for whenever we want to keep an intermediate version around (like if we issued a beta on July 24 with short hash f8b49c2).

Having versioned API docs is useful. Our solution before was nice but it only ever matched the head revision.

jsmcx commented 4 months ago

Thank you for highlighting the OSMD project. As a consumer of both libraries, it always seemed to me that it would be best to have commonalities in the formatting code, so that improvements could benefit everyone.

mscuthbert commented 4 months ago

Thank you for highlighting the OSMD project. As a consumer of both libraries, it always seemed to me that it would be best to have commonalities in the formatting code, so that improvements could benefit everyone.

There was a lot in the v1 formatting code that I really miss now also (especially for lyrics) -- I'm sorry I didn't pay enough attention to the v1 to v3 changes to catch them at the time.

rvilarl commented 4 months ago

For 5.0, I would like to close https://github.com/0xfe/vexflow/issues/573

220

223

@jaredjj3 you?

mscuthbert commented 4 months ago

220 seems well on its way, so I understand wanting to get it into v.5

223 is a newer issue that has come up for the first time later in the v5 development. Could it go into a 5.1 branch issue?

https://github.com/0xfe/vexflow/issues/573 is an issue that has been open since 2017 with no movement or comment for 7 years on it -- why is it suddenly a priority to get in before the next release?

I understand that there are things each of us want in a release, but at present Vexflow is in a stasis position -- people who aren't interested in the font development (like me and several others who have expressed concern) can't contribute to the project until a stable release with the font changes has come out. In the meantime some people for whom fonts are most important are proposing more changes (or APIs to be documented etc.) that are necessary before another release can come about.

In the meantime, contributions to other parts of the library (formatting, layouts, beam improvements) are languishing. My feeling is that a feature freeze for V5 is long overdue (I expressed this feeling to Ron in December of last year) and anything else people want should be in 5.1, 5.2, or (if significantly backwards incompatible) 6.0.

mscuthbert commented 4 months ago

I propose for version 5.0:

  • prioritize fixes and features needed by @rvilarl and @jaredjj3
  • make sure the readme and hello world tutorials make sense
  • have a simple sandbox hosted on codepen/jsfiddle/etc so people can quickly test out vexflow snippets.

I think that the second of these is the only thing to make sure to have for v5. Making sure that the new font-system can be used in the variety of use cases that Vexflow has been in for years (including posting images to GitHub for review without assuming users have certain fonts installed) is the main other thing I see missing for v5.

I'm happy to bump the 5.1, 5.2, 5.3 back one 0.1 release to make the other two issues (prioritize fixes and features needed by @rvilarl and @jaredjj3 -- and the sandbox) be the new 5.1.

Though I think that I haven't been clear about what was useful about the old sandbox -- it let a developer see how Vexflow was running on her or his own development build (that hadn't yet been committed or even PR'd). I don't see how a JSFiddle version of a sandbox substitutes for this feature since it will never take into account the most recent, say beam angle tweak, that a developer had just implemented.

rvilarl commented 4 months ago

@mscuthbert this is the reason for the 3 PRs that I selected

220 seems well on its way, so I understand wanting to get it into v.5

220 was your proposal, and I find it good. I am waiting on a review to confirm that I understood it properly

223 is a newer issue that has come up for the first time later in the v5 development. Could it go into a 5.1 branch issue?

223 is a follow up from #220 as doing the change I realised that the styles were applied more than once on some elements and none on others.

0xfe/vexflow#573 is an issue that has been open since 2017 with no movement or comment for 7 years on it -- why is it suddenly a priority to get in before the next release?

This one is a result of reading style topics in VexFlow4 to check if I was missing something related to the topic. We have now the MetricsDefaults and Metrics.getStyle() I was wondering if it should be ThemeDefaults and Theme.getDefaultStyle() to align with this PR and perhaps make a Theme.setDefaultStyle()

None of the above is a must for 5.0 I am also looking forward to releasing.

rvilarl commented 4 months ago

@ronyeh I am modifying the README and vexflow-examples. Would you use alpha4 references or 5.0.0 on the assumption that it will exist?

ronyeh commented 4 months ago

For now I'd refer to latest alpha at https://cdn.jsdelivr.net/npm/vexflow@alpha/build/cjs/vexflow.js

Hopefully it's not too much hassle. I'd like the README & examples to "always be correct" as much as possible. If we used a release url with 5.0.0, it won't work and someone dropping by will just think our library is broken.

Once we're ready to promote to beta and full release, we can go back and update those README & examples.

rvilarl commented 4 months ago

@mscuthbert @ronyeh @AaronDavidNewman @jaredjj3 I would suggest to make a fix date for the release. If we do not get into 5.0 we will never start getting feedback from other users.

ronyeh commented 4 months ago

Instead of a fixed date for 5.0, I'd prefer if we do it by number of open PR / outstanding issues. If we keep opening new PRs, we will always be playing catch up and the project won't achieve stability (API or behavioral). Let's work on merging these improvements and making sure you and Jared are happy with this version for your projects.

I see there are five PRs open. I can work on reviewing them soon (over the next week or so). Once they are merged, are you and @jaredjj3 happy with the existing feature set / outstanding unresolved issues? We can promote it to beta once there are no outstanding PRs. Then we can test with that beta to make sure we're happy enough to call it 5.0.

For 5.1 we should highly prioritize solving the SVG empty squares issue. I think the most correct solution will be to include the path inside SVG defs or symbol, and then instantiate those paths as needed with use.

To achieve that, we will have to parse the font glyphs at runtime, and this will probably require opentype.js as a dependency.

rvilarl commented 4 months ago

@ronyeh #225 #226 and #227 are not required to proceed. They solve style related issues. I have label with 5.0 the only two relevant PRs.

Quite a while ago I suggested using opentypejs https://github.com/0xfe/vexflow/issues/1399 but it was prefered not to go this way. This is why we moved to use the fonts directly.

I suggest that we list the different use cases and consider pros and cons and even different approaches. I have in mind two use cases but I am sure that this is not the full picture:

jsmcx commented 4 months ago

As I've mentioned before, my main use is generating SVG for embedding in websites, Word documents, and PDFs. I'm obliged to "hot desk", so I can't guarantee availability of a music font on my machine, nor those I'm distributing to. So embedding the glyphs in some way is really important.

Options that have been proposed so far:

  1. The Vexflow 4 approach of having each glyph as an SVG path element Pro: has worked reliably for many years Con: file sizes are bigger than other approaches

  2. Use real music fonts Pro: Smaller files, easier to change to different font Con: Display breaks if person viewing the file doesn't have the font installed.

  3. Embed the font (or a subset) in the generated SVG Pro: Files remain relatively small (beyond initial cost of embedded glyphs) Con: Doesn't render reliably on sites with a strict Content Security Policy. Ironically, GitHub has such a security policy, so demo SVGs may not render if hosted here. Also, use of the <glyph> tag is deprecated, so the font would have to be base64 embedded, which is harder to read/understand/debug.

  4. Embed glyph paths as symbols, and then instantiate those paths as needed with <use> Pro: Files remain relatively small. Doesn't rely on styles or fonts, so should render correctly everywhere. SVG format allows symbols to be individually read/addressed which is helpful if using in an app/game. Con: May be more technically complex to change fonts? (I don't know).

Incidentally, I suspect the other main use case is rendering within apps, as many of the contributors to this old discussion seemed to be doing. In such cases a smaller rendered SVG will help performance, so options 2-4 are all better than the Vexflow 4 approach, but there may be other pros and cons in that scenario that I haven't thought of.

rvilarl commented 4 months ago

@jsmcx there is another option for SVGs:

  1. Embed the font URL in the SVG, this is good to embed in websites but probably not for documents and PDFs.

I believe that a postprocessoing option for SVGs might be acceptable. With a python script as I proposed in https://github.com/vexflow/vexflow/issues/71#issuecomment-2257693914 or using opentypejs.

rvilarl commented 3 months ago

@ronyeh from my point of view, ready for a beta

jsmcx commented 3 months ago

I would view the need for postprocessing as a significant regression. Generated SVGs should be viewable stand-alone with no additional work by the user. Complexity should be handled by the library.

rvilarl commented 3 months ago

I would view the need for postprocessing as a significant regression. Generated SVGs should be viewable stand-alone with no additional work by the user. Complexity should be handled by the library.

I believe we should have different options for the different use cases:

I believe that the last 5 options could be resolved with scripts. These scripts could be instantiated automatically.

ronyeh commented 3 months ago

Let's direct the SVG related discussion over to: https://github.com/vexflow/vexflow/issues/71

ronyeh commented 2 months ago

@rvilarl are there any other PRs coming? If not, we can ship a beta this week.

rvilarl commented 2 months ago

I will not add any PR after #225. Including #225 is not a must.

ronyeh commented 2 months ago

Shipped beta 0.

npm install vexflow@beta

Next steps:

Lets avoid behavior changing PRs and focus on bug fixes and general repo polish (e.g., comments) during this beta testing period.

If you have any improvements that result in behavioral changes, please propose in the discussions: https://github.com/vexflow/vexflow/discussions

The SVG issues will be solved after 5.0, for the 5.1 release.

rvilarl commented 2 months ago

@ronyeh are you ok with shipping a beta 1?

ronyeh commented 1 week ago

Hi, sorry I've been busy. I think I'll have more time to work on VexFlow in early 2025.

I think before shipping v5.0, there should be more documentation / examples, and a simple sandbox so that people can explore the APIs more quickly.

It's OK that there are backwards incompatibilities and (temporary, I hope) regressions. But it is important that we can highlight the new benefits and allow newcomers to learn the API quickly (via wiki docs, easy examples, and the sandbox).

I'd be happy to look into the sandbox / playground for v5.