[META] Proposal for Changes

[RobLoach]

This issue is a meta-discussion about how to increase collaboration from others, and push the library forwards. While we usually want to avoid breaking changes, it can hinder innovation. What I'm proposing is...

• Further adopt Semantic Versioning so that breaking changes are clearer
  • Yes that means more frequent major versions, but it will be clear when a breaking change happens
• Document semantic versioning usage
• Build out the CI to build nuklear.h for us, so that git conflicts don't happen
• Further adoption of Doxygen
• Make a emscripten web-demo embedded as part of the doxygen github pages
• Automated unit testing. While we do build out the demos, would be good to have a simple script that unit tests some of the functionality
• Add another maintainer? Any volunteers?

cc @rswinkle @sleeptightAnsiC

[sleeptightAnsiC]

[Offf, sorry for this being so big]

I guess this is the only place apropriete to do this, so I'm just giving away some of my thoughts and current stance on Nuklear overall

Why I care about Nuklear:

• (IMO) Nuklear is the only real alternative to https://github.com/ocornut/imgui
• (IMO) DearImGui will always be better than everything else (Omar is doing a fantastic job with it) but DearImGui has one fatal flaw: C++ API (if it had C API with C++ implementation, it would be fine for me, but C++ API is just NO NO)
• I feel there are many people like me, that either can't or don't want to use DearImGui for one reason or another, and Nuklear is just perfect for them. I do miss some features, but it's not a deal breaker.

What am I doing right now:

• started by working on SDL3 Renderer demo in #779...
• ...and now reporting and/or fixing all Issues that were found back then (not kidding, I found so many)
• upstreaming goes rather slowly. Something like #862 cost me a lot of time to research, and it took two months from submissions to being merged. I'm also only submitting things that I'm very certain about
• it seems that people are finding SDL3 Renderer demo to be rather nice, I got few DMs about it, and I'm glad this thing was helpful for some, thus I feel motivated to keep supporting and extending it. I'm planning to do a fix pass and at least one additional feature to it soon (when my other PRs get merged)
• For now, I have some time and motivation to be here, so you can see me responding rather quickly...
• ...but I may simply disappear someday, I can't promise I will be there for a long time time (sorry)

About breaking changes:

• Our current CI runners are not able to detect regressions, and don't even compile all code in this repository. Changes of any sort are risky. That just a fact, and I hope that everyone will agree with me, at least on this very one point. I hope this may change soon, I will try to help.
• I'm absolutely against any form of breaking changes that would force people to patch their code in order to update, so things like: changing function synopsis, removing old functions, removing or changing the names of fields from structs/enums, and so on... are just NO NO for me, and no one will change my mind about it (sorry).
• Changes that break the ABI (aka you can update, recompile, and it will work, but not when dynamically linking) I think are fine given the history of this library. So things like: adding new fields in structs, slightly changing behavior and visuals of widgets, changing something than never really worked (aka there was a bug preventing its usage to begin with), or [EDIT: this would not be safe] maybe even changing a type in a struct to a compatible type, I feel, I'm okey with, although I would ask everyone to be very very cautious about it
• There are many special cases, like this one #768 where an incorrect change could simply waste huge amount of someone's time. We have a lot of strange legacy behavior that never really worked as it should. So please, be careful, this code is super tricky.
• When fixing or extending something, please try to do this in backward-compatible manner first, and if that doesn't work for some reason, only then consider a breaking change. Breaking changes are hard to revert, unlike the non-breaking ones.
• When extending the API, always ask yourself: "Will this be enough? Will I want to change it again? If yes, then how?" - and always try to leave some room for changes (I think this is very important)
• For me, backwards compatibility is really serious. This is a C library. People who use C care about compatibility. If you don't care about compatibility, why are using C89 library anyway? This is not some kind of JavaScript framework where you would expect API breakage each release (no offense to web developers)

About bumping the changelog: [EDIT: https://github.com//issues/908 ]

• How about we just abandon the src/CHANGELOG - literally stop updating it, and stop adding it to single-header-file
• Is there anyone who benefits from reading the changelog in this form? If yes, could someone please explain to me what the benefits are? I believe we could add a release changelist from time to time, but this current form doesn't make much sense to me
• Changelog updates introduce bunch of merge conflicts. One PR merged? now every other PR needs to be rebased
• Changelog entries almost always don't feel right. There is less place to explain something than in commit message, and many changes need implementation details in order to be explained correctly, so they're not even worth being mentioned.
• Many cases where it's hard to tell whether it should be noted in changelog or not. If I'm changing some demo code, this should probably not go into the changelog, same with CI and so on...
• ...and in practice, there are many changes missing from changelog, so reading it should not be trusted at this point
• We have git log and https://github.com/Immediate-Mode-UI/Nuklear/commits/master/

About bumping the version:

• same problems as with the changelog...
• ...although we still need it, we can't just remove it
• no one bumps the version in clib.json at this point. Even I forgot about it long ago
• how about, instead of updating it on per-PR basis, the maintainer will update it from time to time
• don't treat major version bums, as something that allows you to break stuff, please

About updating single-header-file:

• I would love to move it to a different repo, and regenare it there by CI...
• ...because having to deal with this file here messes with so many things (git history, regex searches, people wrongly submitting PRs for it, people referencing it instead of ./src/* equivalent, and so on...) ...
• ...but, I guess, way too many people depend on this file being here at this point, so it is here to stay.
• How about I create a similar script to .github/ci_compile_sources.sh that will look for incompatibilities between ./nuklear.h and ./src/* and will block PRs based on it? Still not automatic but should be an improvement.
• Full automatic regeneration of ./nuklear.h would be nice, but I'm afraid people would still submit PRs with changes applied to wrong file (and, I'm not sure how to implement such script correctly, so let me know if you have any ideas)
• Remember that there are people building from ./src/*.c for many reasons. This was broken for several years due to Failure to build #256 but it should be supported.

Few other things worth changing (mainly related to ./Readme.md and community workflows):

• I think, the README is supper outdated, and we should make a general pass on it
• I think, we should remove any image from README, that shows Nuklear created with code that we don't have access to
• We should definitely remove any image that shows (or suggest) a proprietary copyrighted IP (the ones that look like Dia... *ekhemn* blo... and Battle... *ekhem* ...field3). Not only it's scummy thing to show them here, the legality of advertising public domain library with such images is questionable (@RobLoach tagging you here, so you won't miss it 😉 )
• We should add more visible reference to Github Wiki and Discord Server
• We should encourage people to submit Issues instead of PRs, or rather: "Please, report Issue first, before submitting a fix for it" - because there are many PR's that would be a great bug reports, but are instead being submitted as not so correct fixes (e.g. #879) ...
• ... same with features and bigger changes. Let's report them as Issues first, discuss with everyone interested, and only then implement. There are many great feature PR's that had legitimate reason to exist, but have been submitted without any context given, and are left unnoticed for so long (example #777)
• I'm truly annoyed with AI/LLM agents, and I'm pretty sure that you cannot create Public Domain code with it, but I guess we simply can't forbid it here, it's just impossible since Github itself encourages it in some form or another. I think we should at least add some small disclaimer that: "This code is very old and complicated, your AI agent will not understand it correctly" and that: "If you used AI help in any form, disclose it's usage immediately when contributing to this project". Some people use AI for translations, and I don't find it that bad, but sometimes it's so exhausting to deal with to the point, where I feel like I'm getting abused. (I won't point a finger, but if you know, you know)

- We need to figure out something about demos. People care about them and use them as real backends. Those demos are becoming impossible to maintain, and they're the actual starting point for everyone. If people come here, and see the demo doesn't work for them, they leave and never come back.

About web demo, I will just paste my Discord message:

Yea, this would be nice. Not only we would have a place to show stuff,
we could also point people to it in order to test/reproduce issues.
There is this web demo that I sometimes use to check things quickly (https://github.com/DeXP/nuklear-webdemo),
but not only it is super outdated, it was clearly created by some macOS enjoyer,
because the scrollbar navigation is flipped.

But I just want to note few things about the web demo idea:
I never really tested demo/sdl3_renderer on Emscripten myself,
so it probably needs some web browser specific polishing
I think it is almost required for this thing to always show commit message
that it was compiled with, so when people start sending us screenshots and issues from it
we will understand exactly what we are dealing with.
web demo can reuse demo/sdl3_renderer/nuklear_sdl3_renderer.h but
we probably have to write a different main.c for it...
...and also turn on all optional demo examples for it

About unit testing:

• I don't believe anyone would be interested in writing those...
• ...and it would take us ages to get anything useful, I think
• also, how those tests would look like? any ideas? Something similar to: https://github.com/ocornut/imgui_test_engine ?
• I would love to have any automated testing, I just don't believe this is doable at the moment
• How about, we will implement a Nuklear Debugger first? (something that would lery you debug widget states and so on)

About doxygen:

• We need to ensure that we have the same information between Doxygen docs, Github Wikies, and code comments
• Currently, the documentation is largely unmaintained. People just read the code at this point.
• I would rather have documentation that explains some core ideas, and tells you how to setup some things...
• ...than having a very generic API documentation...
• ...because I feel the latter one will always be outdated, and people don't need it as much as the other one.

I can turn some of those points into Issues. If you see something interested here, let me know.

^ @RobLoach

[rswinkle]

• Further adopt Semantic Versioning so that breaking changes are clearer

  • Yes that means more frequent major versions, but it will be clear when a breaking change happens

Yes, yes, 1000 times, yes. I've said my piece before so I won't bother making it again here addressing every one of sleep's arguments. Real substantial progress requires breaking changes. Adapt or die and all that.

• Document semantic versioning usage

Definitely. Lots of people don't really understand it.

• Build out the CI to build nuklear.h for us, so that git conflicts don't happen
• Further adoption of Doxygen
• Make a emscripten web-demo embedded as part of the doxygen github pages

All good stuff. I don't have much experience with emscripten and only a small amount of very out of date doxygen experience but that would be pretty cool to have an embedded demo generated automatically. Probably should be lower priority than the first two though.

• Automated unit testing. While we do build out the demos, would be good to have a simple script that unit tests some of the functionality

This would be nice but more difficult. Like sleep said, maybe it could be a long term goal, to get something even slightly like Dear IMGUI's system.

• Add another maintainer? Any volunteers?

I have never been a maintainer of anything but my own projects (or close enough, being the sole active developer on a project is basically the same) so I have been hesitant to volunteer. However, at this point I think maybe it would be worth it even for what little help I could/would add. Worst case, nothing changes and it's basically a no-op. Best case I actually contribute more than I have been and more actively engage other PR's trying to get them in. Most likely, I'll fall somewhere in the middle. So if you're still interested in adding another maintainer, I guess I'm game.