Closed coclav closed 1 year ago
Hi @coclav, some months ago, I've created a codemod to convert the codebase of mxgraph to be more ES6 friendly including classes
, arrow functions
and using Rollup for module bundle. I used for testing the refactoring the provided examples and most of them works π out of the box, just few adjustment(e.g, bind
methods in some of the abstract classes) I've published the results here. I'll be happy to do the conversion process again with the latest version of the repository, which could be a starting point for addressing both points mentioned in the README.md
Hi @coclav & @adrianhdezm, I'm interested as well to participate :smiley: . Do we start by merging and continuing the work of @adrianhdezm ? Also I don't know the state of unit testing in the project, maybe we can increase it a bit as well during the migration?
Hi @CommunityMan, great idea π, just some comments from my side:
Do we start by merging and continuing the work of @adrianhdezm ?
Merging the code here may not be the optimal approach because it is outdated (~ 6 months old). I recommend, we use the codemod on the existing code, so we can also have the all the changes in the history of this repository.
Hi @adrianhdezm, I never used codemod, but I'll take a look into it today or tomorrow, thanks :smiley:
Hi @adrianhdezm I tried the codemod and encountered some issues, never used babel so I still have to learn a bit before modifying the code. Here are the two errors I got :
/usr/local/bin/node /home/user/development/sources/mxgraph-codemod/src/index.js ../../mxgraph
/home/user/development/sources/mxgraph-codemod/node_modules/@babel/core/lib/transformation/index.js:45
throw e;
^
TypeError: unknown: Cannot read property 'parentPath' of null
at Object.CallExpression (/home/user/development/sources/mxgraph-codemod/src/transforms/proto-to-class.transform.js:106:45)
at NodePath._call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:55:20)
at NodePath.call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:42:17)
at NodePath.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:90:31)
at TraversalContext.visitQueue (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:112:16)
at TraversalContext.visitSingle (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:84:19)
at TraversalContext.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:140:19)
at Function.traverse.node (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/index.js:84:17)
at NodePath.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:97:18)
at TraversalContext.visitQueue (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:112:16) {
code: 'BABEL_TRANSFORM_ERROR'
}
Process finished with exit code 1
Which seems to occurs on the mxRectangleShape, I added a dummy if for the moment to check if 'methodFunctionPath' was not null and see what was generated but I encountered a second error :
/usr/local/bin/node /home/user/development/sources/mxgraph-codemod/src/index.js ../../mxgraph
[BABEL] Note: The code generator has deoptimised the styling of undefined as it exceeds the max of 500KB.
/home/user/development/sources/mxgraph-codemod/node_modules/@babel/core/lib/transformation/index.js:45
throw e;
^
TypeError: unknown: Property init of ForStatement expected node to be of a type ["VariableDeclaration","Expression"] but instead got "ExpressionStatement"
at Object.validate (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/types/lib/definitions/utils.js:132:11)
at validateField (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/types/lib/validators/validate.js:24:9)
at Object.validate (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/types/lib/validators/validate.js:17:3)
at NodePath._replaceWith (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/replacement.js:172:7)
at NodePath.replaceWith (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/replacement.js:156:8)
at Object.CallExpression (/home/user/development/sources/mxgraph-codemod/src/transforms/proto-to-class.transform.js:114:16)
at NodePath._call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:55:20)
at NodePath.call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:42:17)
at NodePath.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:90:31)
at TraversalContext.visitQueue (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:112:16) {
code: 'BABEL_TRANSFORM_ERROR'
Process finished with exit code 1
I'll learn some more babel traverse and analyze the issues asap.
Maybe we could create a separate thread/issue to talk more about it
Hi, I'm interested to participate. our team use mxgraph badly in daily work, we can start by maintaining version, and try to add some feature if needed.
Hi, our team have a strong interest in MxGraph. Also we are using mxgraph in daily work, we can start by maintaining version, and try to add some feature if we could.
Hi, I'm interested to join you and do some work.
Hello, Iβm also interested in modernizing mxgraph. Itβs a great library after all, and Iβm sure people would not want to just abandon it.
It would be great if this project was maintained. We are looking at migrating OWASP Threat Dragon from jointjs to mxgraph, so hope that a community could be formed to support this long term.
Hi @adrianhdezm I tried the codemod and encountered some issues, never used babel so I still have to learn a bit before modifying the code. Here are the two errors I got :
/usr/local/bin/node /home/user/development/sources/mxgraph-codemod/src/index.js ../../mxgraph /home/user/development/sources/mxgraph-codemod/node_modules/@babel/core/lib/transformation/index.js:45 throw e; ^ TypeError: unknown: Cannot read property 'parentPath' of null at Object.CallExpression (/home/user/development/sources/mxgraph-codemod/src/transforms/proto-to-class.transform.js:106:45) at NodePath._call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:55:20) at NodePath.call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:42:17) at NodePath.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:90:31) at TraversalContext.visitQueue (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:112:16) at TraversalContext.visitSingle (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:84:19) at TraversalContext.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:140:19) at Function.traverse.node (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/index.js:84:17) at NodePath.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:97:18) at TraversalContext.visitQueue (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:112:16) { code: 'BABEL_TRANSFORM_ERROR' } Process finished with exit code 1
Which seems to occurs on the mxRectangleShape, I added a dummy if for the moment to check if 'methodFunctionPath' was not null and see what was generated but I encountered a second error :
/usr/local/bin/node /home/user/development/sources/mxgraph-codemod/src/index.js ../../mxgraph [BABEL] Note: The code generator has deoptimised the styling of undefined as it exceeds the max of 500KB. /home/user/development/sources/mxgraph-codemod/node_modules/@babel/core/lib/transformation/index.js:45 throw e; ^ TypeError: unknown: Property init of ForStatement expected node to be of a type ["VariableDeclaration","Expression"] but instead got "ExpressionStatement" at Object.validate (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/types/lib/definitions/utils.js:132:11) at validateField (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/types/lib/validators/validate.js:24:9) at Object.validate (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/types/lib/validators/validate.js:17:3) at NodePath._replaceWith (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/replacement.js:172:7) at NodePath.replaceWith (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/replacement.js:156:8) at Object.CallExpression (/home/user/development/sources/mxgraph-codemod/src/transforms/proto-to-class.transform.js:114:16) at NodePath._call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:55:20) at NodePath.call (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:42:17) at NodePath.visit (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/path/context.js:90:31) at TraversalContext.visitQueue (/home/user/development/sources/mxgraph-codemod/node_modules/@babel/traverse/lib/context.js:112:16) { code: 'BABEL_TRANSFORM_ERROR' Process finished with exit code 1
I'll learn some more babel traverse and analyze the issues asap.
Maybe we could create a separate thread/issue to talk more about it
Try below
/usr/local/bin/node /home/user/development/sources/mxgraph-codemod/src/index.js ../../mxgraph/javascript/src
Has anyone ever considered contributing this project to the OpenJS Foundation? Details at https://openjsf.org/projects
Hello @coreybutler - have you experience of doing this and what would it involve?
Has anyone ever considered contributing this project to the OpenJS Foundation? Details at https://openjsf.org/projects
@jgadsden - my experience is limited, but I do know how it works. One goal of the foundation is to preserve libraries after the original authors leave the project. The foundation helps procure people and resources (sometimes sponsors/funding), and they help setup project governance. The goal is to keep the projects alive and growing. They need a champion (can be more than one person) to submit the project to the foundation, then work with the foundation to get everything in place/coordinate. It's not a trivial effort, but it's not hard either. Several of the projects have a single champion.
The process is documented on the site I linked to.
Hi, I didn't see this until now but I've been converting mxGraph to ES6 with my fork at https://github.com/mcyph/mxgraph.
I'm not too sure how much time I'm going to have myself in the near future but I've already made significant progress and may be able to help with maintaining it. I don't intend to maintain backwards compatibility for all of the modules as I think there needs to be some architectural changes to keep the codebase maintainable going into the future, but the structure+functionality of mxGraph overall seems fairly well thought out as-is in my opinion, even if it uses an older JS code style. I think I will probably keep the class names and function parameters etc the same for the most part.
Notably, I have already removed support for VML/Internet Explorer and Edge before it shifted to the Chromium engine, as I think that significantly eases maintenance.
I've been trying to rewrite the examples with React and next.js - you can see the interface live at https://mxgraph-mcyph.vercel.app/. As of writing it's under active development and things might change quickly.
Hello @mcyph - are your changes something you can create pull requests for in this repo? There seems to be a community forming around this repo that could well support mxgraph in the way you want.
@mcyph thanks for your initiative, it is nice to see things moving π―
I agree with @jgadsden: if we want this move to become a community effort, things have to be shared and reviewed by other people; otherwise you will be alone working on it. For instance, if you propose too much code changes at a time, there will be too much to check/review.
about maintain backwards compatibility for all of the modules
: I agree that some changes must be done to make maintenance easier. For new mxGraph users, compatibility is not an issue, but for existing ones, introducing too much changes in one step could be challenging. I have opened #8 to discuss about this topic (there is too much different discussions in the current issue).
about examples
: I think it is important to keep the examples free of any frameworks or third party lib. Otherwise, we have to find in the example code the mxGraph part which is what we are looking for. I am not saying that we don't have to use any tools/libs/framework to build the examples, nor we cannot provide usage of mxGraph with frameworks. But that the examples source code samples provided to illustrate mxGraph features should be kept as simple as possible and focus only on mxGraph code.
We should open discussions on that topic as well
@coclav can you open the Github discussions in this repository? this will be a better place than this issue
@jgadsden I might be able to - I've made batch changes across probably every javascript file, converting from prototype to class-based inheritance. I've also have made it so all the modules import just what they need to allow for tree-shaking.
If all else fails I haven't changed the main directory structure much, so should be able to check out this repo and open a (very big) PR after copying the modified files over, but that obviously may not be the best option. Either way I should try to make sure as many examples as possible work before considering whether to merge back, as I think they might be the best way of checking coverage across the library.
@tbouffard to be honest I hadn't considered wider impacts because I only found this conversation just before, my main goal was getting things off the ground+maintainable so it could be used for projects as fast as feasible but will definitely keep this in mind, especially if my changes would be in wider use.
The main problems with maintaining compatibility are things like where the examples had module-wide changes to configurations, so settings from one graph can influence others on the same page, and I could see things getting harder to maintain the more complicated+larger apps get. I'll need to go into this in more detail at your linked issue soon as I have time.
Re the examples: currently I'm using React because I thought I would be able to get things working and debugged the fastest with it, but essentially every one of the examples is now divided into the HTML template and the JavaScript code, and I've tried to strip them down to only what's necessary. I should be able to relatively easily remove that dependency once things are more stable, as I've semi-deliberately not been using any significant React or next.js functionality.
I am enthusiastic and amazed by the interest in supporting this project.
I have opened the discussion module so that we can, as a group, start prioritising features
Hello, I'm interested to join you and do some work.
Welcome :)
Hi, I would be glad to participate and help with some issues
Hi @azhozhin and welcome π If you want to provide help, please first have a look at #51. We are looking for people ready to test the typescript rewrite, first by checking the examples, the build, and provide feedback. Then I guess we will able to release an alpha/preview release, work on the documentation update and mxgraph migration guides.
Hello @coclav , I definitely need a modern version of some library like mxGraph for my little browser-based MDSE tool. So, in case of interest, I am ready to provide a really good testing for the new version of mxGraph while developing the tool. Is there any TypeScript version of the mxGraph to start testing? I can provide little contributions as well.
Hi @evonox
As suggested in https://github.com/maxGraph/maxGraph/issues/1#issuecomment-939331684, please first have a look at #51.
The development
branch contains the TypeScript implementation and the instruction to build maxGraph
.
Hi, using mxgraph in the project. Would like to keep it alive (and not only in the form of diagrams.net) and participate in maintaining it as well.
Hey all. We rely heavily on mxgraph at sunshower.io and have forked the project over at https://github.com/aire-ux/mxgraph. We'll be happy to supply bug-fixes and modernization efforts as they arise (we've already implemented a fix for shadow DOM and are considering implementing isometric drawings). If folks would like to contribute over there I would love to have you and would be happy to adopt any community rules or conventions you feel would help the project thrive.
We've also forked typed-mxgraph to make it compatible with the new module name
@josiahhaswell That's nice to see efforts for making mxgraph alive. However, regarding the future, I do not understand the need for a new fork in parallel with the maxGraph effort. There are only a few contributors willing to work on the topic, so dividing them up will probably slow everything down.
That's being said, as maxgraph doesn't provide published release for now, I understand that you may have specific needs that can not be put in maxgraph for now. Can you help us here at maxgraph?
@tbouffard I had given this some thought before forking. Ultimately, we would need to fork this project anyway so that we could
We've already contributed a release to npmjs and added support for shadow DOM. We're working on adding support for isometric figures, and will modernize the codebase as we can. If we can also foster a thriving community, that would be fantastic, but the other considerations take priority for us.
Edit:
Additionally, I'd like to point out that rewriting a project as the first priority upon forking really leaves the folks who depend on the existing, stable, codebase out in the cold. I think the rewrite could be great, but until it's proven, it's really throwing away developer-decades (or centuries) of testing, bug-fixing, and optimization. TypeScript and ES6 introduce a lot of boilerplate upon compilation that can dramatically change the runtime behavior of the actual library that has known and verified runtime characteristics. When and if the typescript rewrite becomes a tested and viable alternative, we will adopt that. I do appreciate that work, but I can't predicate the success of my projects on such an unknown, and won't expect other dependents to, either.
@josiahhaswell I can absolutely understand this - we debated for some time whether our goals such as the tree-shaking could be provided for while providing backwards compatibility, but the conclusion was it wouldn't be possible without making substantial breaking changes.
Because of this, I was wondering whether it would be possible to split into something like "maxGraph-next" and "maxGraph-stable/lts (long-term service)", and keep the old codebase running with new browsers as long as feasible, while building the new one with more substantial architectural changes and new javascript/typescript features. I got snowed under by uni+work in the last few months, and haven't been able to build much on the dev codebase let alone the older one, but others including @junsikshim have kept working on the dev one, and am hoping to keep going on it over the next few months.
Rather than creating more fragmentation by creating different forks in different organisations, I think it would be worth considering separating into two different repos within the maxGraph
organisation. This way, we can reduce the risk of multiple parties separately maintaining the previous version for existing codebases, and make it so the goals of us wanting to use maxGraph with existing code can coexist with those wanting to make changes that can't be made without breaking existing code.
@mcyph In my view, there are several forms of bifurcation: dividing the developer community and dividing the user community. As a member of the latter, I have strong concerns about the direction of this effort. In particular:
It's difficult to understand the motivation for a language port in light of cost-free TypeScript abstractions (annotating the existing source with type declarations and signatures) and the points below.
As I mentioned, thousands of organizations rely on mxgraph in its current incarnation, including its browser support. I see that this project has unilaterally dropped support for several browsers that we and others rely on. Enterprise projects, in particular, need to support IE, non-Chromium Edge, etc. for many years after many projects drop it. Maxgraph dropped support because "it simplified implementation." Yes, supporting these older browsers complicates things, but it is part of the value-proposition of the mxgraph project.
Mxgraph is 471 KB gzipped and minified. For a complete diagramming library that supports ancient browsers, that's pretty darn good. In fact, I don't see many complaints about the size of mxgraph, especially in the context of how it's used (folks using diagramming libraries generally don't care about a few extra seconds of load-time). Moreover, the relatively tight coupling present in mxgraph presents relatively few opportunities for eliminating dead code. Yet I see that the rewrite has chosen to preserve this coupling while introducing TS/ES6 class boilerplate.
It takes a lot of time and experience to recreate a diagramming library. mxGraph is a product of its time, but it works quite well. If the rewrite is only focused on evergreen browsers, it would be substantially easier to create a WebGL/scene-graph-based alternative that provides support for 3D/isometric figures/etc.
I see that PRs made to the main branch have been left untouched for weeks and that basically the entirety of the focus of this effort is being made towards the rewrite, which completely ignores the needs of the existing community.
Documentation is a huge undertaking, and mxGraph is well-documented and exampled.
In short, creating and maintaining a fork requires a lot of time and resources. I did not create ours lightly, but rather in response to the issues with this fork that I've identified above. The user-community seems to have needs that are orthogonal to the goals of this project, and I can't invest time and resources knowing there's a strong risk that they could be rejected by a community that does not share my objectives for the project.
Additionally, I'd like to point out that rewriting a project as the first priority upon forking really leaves the folks who depend on the existing, stable, codebase out in the cold ... When and if the typescript rewrite becomes a tested and viable alternative, we will adopt that. I do appreciate that work, but I can't predicate the success of my projects on such an unknown, and won't expect other dependents to, either.
I have to agree with what @josiahhaswell says here. We should aim for continuity for the maxgraph community, starting with an initial maxgraph release on the same codebase as the final mxgraph release. Changes / rewrites can then be introduced after (a lot of) regression testing
We strongly considered mxgraph / maxgraph for OWASP Threat Dragon project but in the end could not go ahead with maxgraph, for all the points @josiahhaswell lists above. The next TD version 2.0 will be using drawing package https://www.npmjs.com/package/@antv/x6
Thanks @josiahhaswell + @jgadsden, I do tend to agree with many of your points. Unfortunately I don't have the time or energy to contribute for the time being and so think I should leave it to others here to decide the future of this project, however:
My view is that if wanting to build on the project, as opposed to maintain compatibility, TypeScript can make a major difference over just having external type definitions. But I feel that in the current development version of maxGraph it's been separated into too many pieces. For this reason I do feel that your "stable" version perhaps should be the standard release. The main reason I was wondering whether creating a separate "stable" project in maxGraph was to make sure there weren't multiple parties maintaining the existing stable release, but if you prefer to keep it separate I understand.
It would virtually be a fulltime job to keep it maintained let alone build on it substantially. I don't think it would be easier to rebuild something like maxGraph in WebGL because much of mxGraph/jsGraph was not based on limitations of technology but because what was implemented was so inherently complex and needed object oriented designs etc. It would be possible to implement aspects of it in less/simpler code, but I personally doubt something with mxGraph's level of functionality would be significantly easier the second time around. If I had more time my preference would be to backtrack on some of the design changes which would make porting to the new code more difficult, but maintaining support for VML doesn't make sense to me when SVG support is available in IE9 onwards even with the Trident engine.
Adding a short note to this, the current state of the development branch's typescript is incomplete with many red-underlined errors all the way through, so the conclusions being drawn about typescript are premature at best. I have said multiple times I think there is a place for maintaining the old version as well as a new version with modern programming style for new applications - I don't currently use m(a)xGraph in my applications, but a lot of the motivation I had with building on it was so I can use it in the future. I kept running into limitations due to e.g. the use of global assigning of variables into prototypes, and using the existing release was not an option for me.
I can't promise ongoing support, but I do have some free time now over the next few weeks, and looking into it over the last two days I don't think it's hugely far off getting something releasable. As a result, I intend to get the typescript errors down to zero, get autogeneration of the documentation support working, with the goal of making the codebase easier to understand for new users and maintenance going forwards.
I don't currently use m(a)xGraph in my applications, but a lot of the motivation I had with building on it was so I can use it in the future.
I agree with you. I'v been working on a project (using mxGraph 4.2.2) for over half year and would like to use a more morden lib.
As a result, I intend to get the typescript errors down to zero, get autogeneration of the documentation support working, with the goal of making the codebase easier to understand for new users and maintenance going forwards.
Is there anything I can do for this?
Is there anything I can do for this?
I've done a fair % of the red underlines in the bleeding-edge branch and hope to get as many finished off as I can in next few days. I've made some fairly large changes to the way things are organised as well as batch changes to remove boilerplate and convert from NaturalDocs to JSDoc. I'm hoping once all the typing is done (and I think we're closer to that than I thought) that there will only need to be changes in single or just a few files at once, and that once that happens it'll be easier for more people to collaborate on the codebase at once and stabilise things.
One thing that I think will be high priority going forwards is checking and updating the examples and documentation to make sure the parameters and explanations match the what the code says. Another thing is just alerting us to issues/bugs and giving suggestions on alternative ways of doing things. In many cases decisions we've made were based on available time and what we knew was possible with TypeScript/JavaScript, but that doesn't mean the way we've done it is necessarily the best. Especially before a stable release when we won't be able to make these kinds of changes as easily, if you have any other ideas about how things could be done architecture-wise please let us know in the Discussions tab.
One thing that I think will be high priority going forwards is checking and updating the examples and documentation to make sure the parameters and explanations match the what the code says.
Indeed, consistent examples and well documenting improves the adoption rate of the library. More examples are welcome
Indeed, consistent examples and well documenting improves the adoption rate of the library. More examples are welcome
@deka absolutely - there's been a lot of documentation and example updates with the bleeding-edge branch that's now merged into https://github.com/maxGraph/maxGraph/tree/development, and with all the type annotations added and red underlined errors in the core lib now removed I'm hoping this will be a good step forwards.
Some of the examples still need to be converted, and the docs still need to be updated, but pull requests are very welcome - because I think it's likely we won't be making codebase-wide changes as often from now onwards, I'm hoping this will also allow more people to contribute at once and to focus on functionality etc without having as many merge issues from people working on the same files at once.
Closing as we are preparing v0.1.0
Hello, we would like to evaluate interest in forming a community of contributors / maintainers of the mxGraph project. Please answer to this issue if you are interested.