#Suphle Rant 8: Strange star discovered

I was searching for a project I'd starred earlier, on my github feed, when I realised a user had starred suphle at some point but for some reason, it wasn't reflecting on the stargazers. I was half overjoyed and half confused. Overjoyed over unlocking the milestone.

User seemed legit –an Italian with projects in C that were not forked. Followers and commit graph are organic. Did he star in error, feel the project is a stinker, or encounter installation challenges? Luckily, I found his email address but all his repositories are in Italian so I wasn't too sure he'd understand English, or if the mail was being attended to. Yet, I took my chances

He surprisingly got back to me, affirming that the star-unstar was actually deliberate. He withdrew the star cuz project's documentation is not hosted online and still requires npm start.

I try to persuade him by reminding him it's just a one liner but that markdown files are equally rendered directly on github. Never heard from him again, sadly

I'm kind of bothered cos I find it funny I thought suphle's APIs are all cast in stone, but the more I work on the docs, the closer I am to spotting something that doesn't sit right with me, and diving in to modify it. This not only prolongs ETA, there's the risk of someone who may have stumbled upon it and is studying it, having the rug pulled from under their feet. Things like validator rules and route-collection service-coordinators have been converted from methods and classes to native decorators. I guess I'm safe since nobody has indicated any signal to the contrary. It'll be pedantic to start tagging versions for each change.

Another consideration is that these breaking changes would go to the first segment of the semver scheme, which is hilarious because the rate at which I push such changes is so alarming, we'd probably progress through 15 versions under a year

If your semver is 0.*, you can do whatever you want. Once you hit 1.*, then people are allowed to get annoyed with you.

A major benefit of using an external framework is that you can point new hires to the vast documentation and community of that framework. If the framework keeps outdating the communities' experience on a regular basis, it basically demotes itself to the same level as the common inhouse framework - just that it isn't tailored to the specific needs of the company.

Try to find a working API structure, test it, make it convenient and performant. Then freeze it and increase the major version number. After ten years reevaluate the API structure and decide that it is still good enough - and keep it frozen.

@Oktokolo what happens if you are a perfectionist with ocd for not tolerating the slightest room for improvement? Suphle should long have been completed if it weren't for my penchant for releasing something with potential to be criticized.

For example, on the php subreddit, I countered the denial by the author of roadrunner that frameworks with an adapter for its server don't need a way to wipe request-context-aware objects in between requests, otherwise they'll stick around. We spoke a bit about it and he sent me a link to a Container-scopes implementation in c#. At this point, suphle had already met all items on the roadmap. I already had a convenient and proven way of wiping those objects but I couldn't help myself. I made 2 separate attempts to implement it, eventually limited by php itself. Wasted about 2 weeks

What if I succeeded and the implication was a breaking change?

@Nmeri17 Perfectionists don't realease software. They just build on it until they die or abandon the project 😛

If you are a perfectionist, maybe limiting the scope of the software you make is a good idea. Application frameworks normally are pretty huge lumps of code with shittons of opportunities for feature creep and obsessing over minor details. Not the ideal type of project for a perfectionist. Try something a few orders of magnitude smaller. Maybe a tool or lib doing one thing exactly right.

@Oktokolo "a smaller tool", you say. You realise it was precisely because of the enormous dissatisfaction with framework functionality that we started this journey in the first place?

I'm sure the reason this fixes are cropping up are because I'm still loitering around the codebase while writing the docs. All that's left is to round up the testing chapter then flesh out the Appendix. Anything that escapes the length of time I've spent immersed in the system is arguably worth it

Which raises another concern: if things become perfect for too long, developers interpret it as an abandoned project no longer receiving updates, and withdraw

@Nmeri17 *these fixes

But I admit that basing projects off a platform making disruptive modifications too soon is unacceptable. I'm not supporting or saying I intend to do it. Even my OP gives the caveat that I'm getting away with it now because, hopefully, nobody is studying it (or if they are, that they're aware it's in molten form)

I hope not to have given that impression

Imho your rant shows a severe lack of understanding that software can evolve in a proper manner.

Semver is *one* way of versioning.

Semver focuses on two things which seem obvious, but aren't:

1) Stability of an API
2) Definition of a version number grammar and constraints regarding versioning

The most misunderstood part is imho one.

The second is less misunderstood, but the deeper one goes, it still leaves - despite being pretty good written - room for interpretation.

You're saying that Suphles APIs are cast in stone.

It would be interesting to know what kind of API you mean? Semver specifically targets the *public* API, not the internal one. I know that this might seem obvious - but I know a lot of devs who overlook this important detail, thinking they have to increment a major|minor version with each change. *Public* API should be a small portion of the whole codebase, even in frameworks.

Another misunderstanding I often encounter is what changing an API means - e.g. addition is not a breaking change, addition of e.g. a parameter can be done by adding another API call, marking the existing one as deprecated etc.

But the most important thing is imho to not change lightly an API. Release early, release often has become a rather dangerous mindset imho, at least if it involves breaking the API regularly.

You might find things you want to change, that's good. Collect them. Seek feedback, e.g. from users or other devs.

Categorize: Is it an API break that has an *important* value, e.g.
1) performance
2) quality / robustness
3) accessibility / usability
...
Or is it an API break that caters mostly to fix "ugliness" inside the code base? E.g. things like "it would be easier to remove that parameter, cause then the respective code would be so much prettier". This caters mostly to the *dev* side. Not saying it's bad - but if you prioritize the *dev* side above all, your users / clients will be unhappy...

The question should not be wether to break the API - rather when and how to create a balance between "breaking" stuff vs "value".

Classic cost vs profit so to say.

No one likes migrations, especially not when they seem to be randomly put in just cause the dev found another funny way of programming they have to test out....

The last sentence is the most important one.

Other people consume your library - they're important. Don't turn them into guinea pigs.

Plan properly ahead, strategize and make API breaks known ahead by utilizing deprecation and e.g. stuff like blogging / planned changes etc.

@IntrusionCM some helpful points were raised towards the end

I'm not talking about public vs private, argument count, etc. I already mentioned the migration from getter methods and classes to decorators. Fairly recently, I made fundamental changes that affect high level behavior: I had it noted as low priority to fix the hack I use in restoring database connections after it's reset by an incoming request (since this triggers a Container sweep). When I succeeded, my solution took me down a rabbit hole of other big changes eg all modules and their dependencies are booted at compile time so all event binding can take place, etc

First thing I want to point out –I already did before and I'm still doing again: these aren't whimsical changes to try out something cool.

2) It's 2 deprecations (on the orm layer, at least), with breaking changes rippling across. Do you play the blind eye or release a major version? What if (hypothetically) this discovery is in quick succession to another?

My thought is that the ratio of such fundamental changes would reduce over time. My todo is not an infinite list. It eventually reaches a point where code freezes, a concern I raised in an earlier comment. I'm not inconsiderate or unempathetic enough to push changes onto strangers. On this very thread, I'm celebrating getting just one github star. You think I'd deliberately treat them carelessly? Inasmuch as I'm passionate about suphle's growth and beauty, that would amount to nothing if nobody actually uses it cuz they're frustrated at its instability. I have this in mind

@Nmeri17 Don't worry, things aren't becoming perfect. Not for a short - and certainly not for a long duration... We are talking about software after all.