Add list of 2.x changes to the p5.js-compatibility README

[davepagurek]

We have some lists in the descriptions of #1 and #2. At some point (this can be post-2.0 launch if need be) it would be good to collect all of these changes in one visible spot in the readme.

[ksen0]

It might be also useful to check the 2.0.0 release notes.

[ksen0]

The scope of this task is to update the README of this repo to have a single visible list of all changes, with clear indication which changes have which compatibility add-on, and which transition steps are needed. This should preferably address both authors of sketches, and authors of add-on libraries (see also: this add-on library system in 2.0 and transitioning from 1.x guide).

Keeping this as "open for discussion" because that's quite an ambitious scope for a one-page README, so ideas are welcome on how to best present this information!

This would be a good first issue for a new contributor already familiar with p5.js 1.x and wanting to really get more in-depth understandigng of 2.x

[GregStanton]

HI @davepagurek and @ksen0! Glad to see this issue.

Spreadsheet -> Markdown?

Maybe as a start, I could add a Markdown document to this repo with all the feature changes we know about, based on the spreadsheet that was being used internally? It's possible that the spreadsheet is still incomplete, but it may be a good starting point, and posting a public version would help if any other contributors want to get involved.

Aside: Documenting other 2.0 changes

Since we're talking about documenting changes, would it make sense to turn the remaining tasks from the 2.0 documentation project into GitHub issues? That way, they could be publicly tracked in p5.js Documentation Update and Organization
. Right now, it looks like the p5.js 2.x project tracker is also being used for this purpose, but maybe we could consolidate documentation issues in the documentation-update project? I'd be happy to post GitHub issues for the remaining work. Here are some examples:

• Reference updates and fixes
  • p5.Vector
    • descriptions may mention x, y, z but not support for n-dimensional vectors (e.g. in sub())
    • clampToZero() is missing
    • mult() examples disappeared along with some of its description
    • etc.
  • sense checks of all pages (@perminder-17 already identified some problems that need to be fixed)
• Contributor docs need updates
  • YUIDoc is still mentioned
  • outdated FES files are referred to
  • new system for add-on libraries not documented in "Creating an Addon Library" (maybe the dev.to write-up could help)
  • new test framework (docs still refer to Mocha)
  • New benchmarking system? I haven't looked into this, but the proposal to expand performance profiling was closed as completed, so I guess we have something worth documenting?
• Tutorials (some are still missing)

There are other tasks that I know are already being tracked on GitHub, but I don't think the ones above are currently being tracked, apart from some smaller issues related to broken links: #7220, #7227

[ksen0]

I could add a Markdown document to this repo with all the feature changes we know about, based on the spreadsheet that was being used internally

That sounds great, please go ahead, do you think it should be an additional .md file or a wiki page? .md file seems more findable, but I'm open to ideas.

Right now, it looks like the p5.js 2.x 🌱🌳 is also being used for this purpose, but maybe we could consolidate documentation issues in the documentation-update project?

Anything that's help wanted and good first issue can be cross-posted on both boards, since I'm using the 2.x status board as the main link to invite contributors, and it should ideally include documentation tasks

new system for add-on libraries not documented in "Creating an Addon Library" (maybe the dev.to write-up could help)

Recently created, also relevant: processing/p5.js#7798

[quinton-ashley]

Mentioning that p5 v2 doesn't add instance props to the global scope anymore would be good.

[GregStanton]

Hi @ksen0! Sorry for the delay. Thanks for pointing out the new add-on library documentation, and thanks so much @limzykenneth for publishing that! Very helpful.

That sounds great, please go ahead, do you think it should be an additional .md file or a wiki page? .md file seems more findable, but I'm open to ideas.

Oh, good idea! A wiki would be easier to edit, and we could make it more discoverable with a prominent link from the README, for example. I guess it depends partly on how you want to set permissions for wiki editing. In case you want to consider a fully open wiki, I guess it's worth saying that the full commit history will be available, and it's possible to revert unwanted changes with a click. But that'd require monitoring changes, etc. Just let me know what you think is best.

Anything that's help wanted and good first issue can be cross-posted on both boards, since I'm using the 2.x status board as the main link to invite contributors, and it should ideally include documentation tasks

Sounds good!

[ksen0]

Hi @GregStanton ! Re: libraries - recently @limzykenneth also added https://github.com/processing/p5.js/blob/dev-2.0/contributor_docs/creating_libraries.md https://beta.p5js.org/contribute/creating_libraries/ which may be helpful as well.

Good point about wiki editing - fully opening it would introduce a new monitoring task, so it's not a casual change. But it does seem like something really worth thinking through in the future.

For now, let's keep as much as possible in README (in a section at the end?) or .md files? I don't mean to block the 2.x changes documentation with the wiki idea. Let me know if you still have capacity and interest to work on:

Maybe as a start, I could add a Markdown document to this repo with all the feature changes we know about, based on the spreadsheet that was being used internally?

[GregStanton]

@quinton-ashley Thanks! Is it possible to provide a short summary of the change to how instance properties are handled, with regard to how it affects end users or add-on developers, perhaps with an example? It looks like there's been extensive discussion that's since led to more GitHub issues, so if anyone can offer a short summary, that'd be helpful. Or, if the situation isn't settled yet, that'd be helpful to know too, since I could tag this change accordingly in the wiki/md doc.

[GregStanton]

Hi @ksen0! Makes sense.

I can add a concise list of changes to the README. I can also post issues on the main p5 repo to invite contributors to help with any remaining documentation work, and I can crosspost to the p5.js 2.x and the p5.js Documentation project trackers.

Is there any kind of timeline you'd like to see for this? My upcoming tasks (in the order I plan to do them) look like this:

1. Publish Transform/Matrix proposals on GitHub
2. Finish updates to shape docs
3. Post list of known 2.0 changes in this repo's README + GitHub issues for any remaining 2.0 documentation tasks
4. Many other things 😅

I started working on the matrix features because I initially had the impression that work was going forward, and I wanted to have a chance to share my thoughts before things got too far along... I've made a ton of progress, and I'm close to being able to publish a concrete roadmap on GitHub. Would it work for you if I wrap up this work by early next week, and then get going on the other tasks in the list above?

If not, I'd be happy to reorder my task list. I think the documentation tasks are actually more pressing, especially now that it looks like we have a bit more time for the transform and matrix features.

[ksen0]

Hi @GregStanton thanks for your work on this!

1. Transform/Matrix proposals- thanks for your work and patience on this, I still haven't had the chance to deeply go through your notes about this yet, and consolidate and share the notes form other related conversations about TransformMatrix. The main thing that could be part of 2.1 would be the TransformMatrix, following very closely to the work that's already done and minimally expose the more graphics use cases (mindful of your checklist about some of the tasks on prerequisites about that). There is no rush on the general case.
2. Especially if the shape docs are addressing errors, those might be higher-urgency than the Matrix work?
3. I agree this follows both of those. The list of changes is currently relatively visible in the release notes but will be less understandable just through those over time, so I think it'll get more pressing with time.

If not, I'd be happy to reorder my task list. I think the documentation tasks are actually more pressing, especially now that it looks like we have a bit more time for the transform and matrix features.

I would agree with that, it's not the intent to rush anything, and correcting documentation gaps is the main priority across the board.

[GregStanton]

Hi @ksen0! I'm glad to help.

1. It may be best that you haven't had the chance to deeply go through the notes I shared... Those were works in progress to keep you up to date, but I've iterated many times since then. Along with a new architecture and other improvements, my new idea includes some API changes, including to the Transform class itself (in my new way of thinking about it, I think we can just call it Transform rather than TransformMatrix, in keeping with a suggestion from @davepagurek). In short, everything is in line with what we've discussed, but there are changes I plan to propose. I also plan to speak with @holomorfo about this early next week.

2. I'd love to switch over to the shape docs to address some issues I found; however, if the goal is to keep work going on the transform features for 2.1, it may be best for me to publish what I have on those first.

3. Makes sense about the prioritization of the list of changes!

Also, just FYI this week will be a little slow for me, as I have family in town, but I should be able to put in some time again this weekend, if not sooner. If it helps, I could publish what I have on the Transform class by the beginning of next week. Or I could push some changes to the shape docs, per your guidance.