Frontend discussion: jQuery & Fomantic-UI

[wxiaoguang]

There are many discussions about the frontend refactorings, this issue is to record the details, and avoid bikeshedding in future.

Background

Gitea is using DOM Native, jQuery and Vue2 together, the UI part is heavily using Fomantic-UI.

Discussion Topics

Should Gitea use a new UI framework?

Some maintainers mentioned Tailwind CSS before.

Gitea frontend now uses Fomantic-UI components heavily, ex: Dropdown, Modal, Checkbox, etc.

Currently there is no conclusion or detailed plan about how to migrate the UI to a new framework.

Should Gitea drop jQuery?

The mentioned Cons of jQuery are:

jQuery Performance

Question: jQuery was proven to be much slower than native (sometimes as much as 10x), just look at their code which is full of hacks to support weird edge cases and legacy browsers. While the performance difference will probably not matter in most cases, I still think it's unnecessary baggage we can avoid by using the underlying APIs directly.

Discussion: In most time it is not that slow and it doesn't affect user experience. JS is slower than C but it doesn't mean that we should write everything in C.

jQuery Popularity

Question: Modern web developers don't even learn this API any more (SPA frameworks strongly discourage jQuery), so the contributor base that knows jQuery will shrink over time.

Discussion: The current situation is: Gitea has a lot of legacy MVC code and uses many jQuery features: event system, ajax, filter and chained-call $().parent().foo().bar(). If we drop jQuery, we would rewrite them all and introduce a house-made jQuery-like framework. if we replace jQuery with a home-made framework, it would be much less popular than jQuery.

Potential Problems for Refacotring

New PRs using jQuery during migration

Question: If we start the migration, a new PR uses jQuery, what should we do? Force the contributor to rewrite, or we rewrite for them, or just accept it?

Discussion: It's not friendly to force contributors to rewrite without jQuery. If we accept the new PRs with jQuery then new code comes and the percentage of jQuery increases. No conclusion yet.

Continuity

If we decide to start the refactoring, we should guarantee it can succeed. If we stop half-way, then more and more frameworks would be mixed together, it would be a big disaster. That's why we should think carefully and have a clear plan before we continue.

End-to-end tests

by singuliere: The primary problem with refactoring the UI is the lack of end to end testing (e.g. running a browser and have a test click on the web page, using a selenium driver). Not that it will make it impossible. Just significantly more difficult and prone to regressions. It would make sense to start with adding a reasonable amount of end to end testing so that the result of a human interaction with the UI can conveniently be verified to not change after the framework is replaced.

by wxiaoguang: If we do framework level migration and refactoring, then the pages should be rewritten, then all old tests become invalid and should be rewritten too. So the tests had better to be written in a long-term & stable framework.

Next Step

If we choose to drop jQuery, before we make a final decision, we should document all detailed steps about:

1. How to deal with Fomantic-UI and its components? If we still use Fomantic-UI heavily, jQuery is a must.
2. How will the home-made library for jQuery replacement look like?
3. How can we guarantee the refactoring succeed? We can not stop half-way, otherwise there would be a big disaster.

If we choose to continue using jQuery and Fomantic-UI, we can make some new guidelines.

[singuliere]

The primary problem with refactoring the UI is the lack of end to end testing (e.g. running a browser and have a test click on the web page, using a selenium driver). Not that it will make it impossible. Just significantly more difficult and prone to regressions. It would make sense to start with adding a reasonable amount of end to end testing so that the result of a human interaction with the UI can conveniently be verified to not change after the framework is replaced.

[wxiaoguang]

The primary problem with refactoring the UI is the lack of end to end testing (e.g. running a browser and have a test click on the web page, using a selenium driver). Not that it will make it impossible. Just significantly more difficult and prone to regressions. It would make sense to start with adding a reasonable amount of end to end testing so that the result of a human interaction with the UI can conveniently be verified to not change after the framework is replaced.

If we do framework level migration and refactoring, then the pages should be rewritten, then all old tests become invalid and should be rewritten too. So the tests had better to be written in a long-term & stable framework.

[kdumontnu]

The primary problem with refactoring the UI is the lack of end to end testing

I completely agree. I don’t have a strong opinion for what front-end test tool to use, but I checked out some options last year. BackstopJS and Cypress seemed like the two best contenders. Backstop is cool, but the problem is where to save the screenshot data without blowing up our repo size (or adding LFS dependency).

I think Cypress is the best contender. They have a free open source offering, you can test across different browsers, and there is a ton of support and integrations. The downside is that its a bespoke testbed language.

I don’t have a ton of time to develop this near term, but I would be happy to help get things set up and help sponsor development.

[techknowlogick]

While I am still reading through the above, I'd also like to explicitly state accessibility as part of the acceptance criteria.

[silverwind]

Regarding jQuery, we can use eslint-plugin-jquery to gradually migrate off of it. Each time a new feature is refactored, a lint rule can be enabled to forbid it. For example, refactor .ajax to fetch and then enable jquery/no-ajax.

[kolaente]

My two cents:

• I don't think we should build a home-made js framework and use that instead of jQuery. We'll probably be better off using something already made that fits our use case. I've had a good experience using alpine js for these kinds of things, in a similar sized codebase than Gitea. The same is true for tailwind. I personally don't like foomatic UI because of its age and all the hacks it has, back from a time when we did not have flexbox. Maybe a good idea to check what the foomatic community thinks about this and what they plan?
• Another option would be to build an entirely new framework. This has mostly downsides though: we can't do it gradually, we need to choose a framework which everyone knows and it increases the barrier for contribution. The only upside is we'd have a very nice, state-of-the-art Frontend (at least for a few years until the next shiny thing comes around). But it would be so much work to build it, and will likely always lag behind as we keep adding new features.
• From my experience, cypress wins over selenium.

[tboerger]

My two cents:

• Start using more VueJS instead of jQuery everywhere. No way to start writing a custom framework!
• Tailwind CSS sounds like a good replacement for the current CSS framework
• Enable eslint-plugin-jquery to prevent reintroduction of jQuery functions within pull-requests

[silverwind]

If we drop jQuery, we would rewrite them all and introduce a house-made jQuery-like framework. if we replace jQuery with a home-made framework, it would be much less popular than jQuery.

No library/frameworks/wrappers of such kinds please. Modern DOM APIs are potent enough to be used without wrappers. Cases like fetch could be wrapped for the purpose of authentication/CSRF token, but generally we should just use them as they are.

[wxiaoguang]

If we drop jQuery, we would rewrite them all and introduce a house-made jQuery-like framework. if we replace jQuery with a home-made framework, it would be much less popular than jQuery.

No library/frameworks/wrappers of such kinds please. Modern DOM APIs are potent enough to be used without wrappers. Cases like fetch could be wrapped for the purpose of authentication/CSRF token, but generally we should just use them as they are.

I was not talking about ajax. I mean, what about these chained-calls $().parent().foo().bar()? What's the best method to rewrite these code without jQuery while keeping the code clear and correct?

[lafriks]

If we would rewrite dynamic parts to Vue we would not need such constructs

[wxiaoguang]

If we would rewrite dynamic parts to Vue we would not need such constructs

I agree new frameworks won't need such problems.

The reality is, Gitea uses a lot jQuery and Fomantic-UI. Everyone knows "what to do" is better, but it doesn't help now. I still want to mention that recently some new code were written in Vue but it only makes the index.js more messy.

If we can clarify "how to do" ahead and make everyone work together, we could achieve the goal.

A question is: do most of us agree to only write Vue code in future and never touch jQuery and Fomantic-UI any more? If yes, we can write this agreement down and discuss how to start rewriting old code.

[Matt-Deacalion]

For end to end testing, Playwright and TestCafe are worth adding as options. Playwright may be able to write front end tests in Go.

[miku86]

Does anyone have some data?

E.g.

• How many contributors know these new tools?
• How many pages use these old tools?
• How many pages would we have to rewrite?

[wxiaoguang]

How many pages use these old tools?

Almost all.

How many pages would we have to rewrite?

Almost all if we want to drop them.