Next milestone

[herzinger]

First of all, I'd like to say sorry for the hold up in the changelog PR. Long story short, I had some personal stuff going on and because of that I became virtually inactive in many projects for the last few months, but I'm mostly back now.

I'll share my two cents in the new PR (#309) opened by @csshugs on that issue shortly, but this issue is more of a question/opinion on the future of the project, based on the current insight stats and my experience with other projects and with troubleshooting in the slack channel I manage for inuitcss itself.

I wasn't here to comment on it, but the decision to launch the 6.0.0-beta.5, even without the changelog was a good one. Is was badly needed, and this feature wasn't that much of a deal breaker not to have at that point, not enough to hold the whole project back. But I also noticed the new PR referenced above is marked under a 6.0.0-beta.6 milestone tag, which made me think: Do we really need another beta?

I can't think of any major feature being added before launch, outside of:

• The changelog itself
• The badly needed fix for the line-heights calculation discussed in Proper graphic design baseline. #279 and Is the out-of-the h1-6 formatting commonly accepted? Looks ugly to me... #291 (and yes, that's also on me, I'll finally finish my proposal now)
• The approval and merging - or closing - of the other currently open pull requests
• Most of all, proper documentation outside the in-code comments

Anything else should be just fine tuning based on the issues we find and/or are reported by our beta users, and that should be the underlining theme of this next milestone, with the 6.0.0 version release in mind.

Most of the issues bought to me at this point are related to usage and, to my understanding, are fruit of the lack of easy to follow documentation and examples, that's all. There are bound to be some real issues, like the responsive cascading one reported in #303, and that is the kind of thing we should focus on in this last run to a proper release. The massive fall of activity here lately is another signal we are in the final stretch to the release landmark.

I suggest we create the 6.0.0 milestone tag, finish up what was started already, discuss the matter of documentation once and for all (I still think that automation is the way to go, and that it would bring way more value than any setback, like the thing about the commenting style and stuff like that, if done properly, but if not, then what? I can assure the commenting alone doesn't do the trick for many users), and use the rest of this milestone to do a major code review.

The framework is already stable enough, and we can always continue working with minor and patch releases from then on, and even start looking ahead to more extreme changes in a future 7.0.0 version eventually, but we can't fall in the trap that is the perenial beta.

[anselmh]

I agree that a missing changelog shouldn’t hinder us from releasing a beta or stable version. This feature can always be introduced as minor version later on.

[dnwhte]

Any update on this?

[herzinger]

As promised in #353, let's continue here. Again, all in here is my personal opinion, and yes, it's a bit of a rant. What follows is a series of suggestions and commentaries from someone who follows this project from the very beginning (more on that later) and has some experience in the area.

1. About versioning (and beta releases)

Inuitcss is not in a beta stage for a long while now. It is a 1100+ stars framework used in countless projects in the wild. I've seen it used in sites, internally in CMS's and even in bootstrap-like ui toolkits. Hell, I've written two of those myself as part of component kits / brand guides. It's probably not a stretch to call it one of the best/more successful frameworks in it's niche, to the point of we having to explain a bunch of times that no, it's not trying to compete with bootstrap, it's a different beast altogether. That being said, there are 133 forks of this project right now in github alone, and that's only the ones made through the official means and not simply copying large parts of the codebase and pasting it somewhere else. I'll argue most of those are not people forking to make pull requests.

I did maintain a fork myself for a long time, and it did fork quite a bit before I decided to kill it and start contributing to the main repository. I did it because, in v6, it was going in a similar direction of what I had in mind when I decided to fork out in the first place. It's been around 2 years since then, and this stable v6 was never released yet. As I said before, I believe Inuitcss to be a proven, stable framework for a while, so what would I do different in regards to versioning (finally!)?

First, I would move out of beta as soon as possible. Only major releases need beta versions, and only big refactors, or a change in philosophy/methodology need major versioning. I'd move out as soon as all the main components of the framework that existed before the refactor, or similar ones, were revised and usable, giving it just a bit of time in the brave hands of the beta users, in order to catch possible hard bugs. From then, every approved merge should get a version release. That's how I work in the projects I manage, and it's specially true for a framework. Every merge should get a tag. A patch release (think something like v6.0.1) if it's small and/or safe, and a minor (v6.1.0) if it brings possible breaking changes, or if it brings whole new features. That's what those numbers exist for. It makes no sense to stay in beta until the x.0.0 release, and them move on to the next beta. Yes, bugs will appear in stable versions, and they will be patched.

It's pretty common that I start on a new project with inuitcss, decide to use one object or something from the framework, see it looking different from what I remember and then come and see that that particular merged change was never released in the official npm package. In my current project I use inuitcss, like always, but most of the partials are commented out, and I'm using different versions I wrote myself, either with changes pulled out of the develop branch or simply different implementations, and that is because we take so long to release anything, even in the little bursts of activity the repository gets sometimes.

Little aside: Our main branch is the develop branch. It means when an user comes to our github page and look at some of the in-code documentation, this is the branch they see first. And this branch is not the one equivalent to what is in the package managers. And talking about the in-code documentation...

2. Documentation

In-code documentation is not good documentation, not for the user at least, no. It is great, and a good practice, and it should absolutely be done with discipline, but it's mostly useful for framework maintainers, and just barely for the final users. It was never great, and in today's world of node_modules and bower_components it's even worse. People don't want to go through their dependencies code to find out what that particular class does, or how that object should be used, or what features/modifiers exist even, nor they want to navigate through github source pages, and in the end have to interpret some little descriptions and numbered comments, with no visual/actual examples, best practices and other stuff like that. Still in this topic: with our ecosystem of build systems and optimizations, commented code output is pretty worthless. When was the last time you opened the un-minified output css to look for something that some comment block would help you with? Again, all of that is good and should still be done, but it will never justify lack of proper documentation for a framework. I've been pretty vocal about my opinion on automated documentation via SassDoc or something similar, but for a quick, just a little better solution, even a small markdown file in each object, component, utility, etc, would be a good start. No one here has the time or disposition to maintain a full blown site for all of that (that's mainly why automation would be great), but we do need proper documentation, and I would be glad to help with that as much as possible. Inuitcss is great for me, but I know it inside out, that's not the case for most users. Most of the questions in that troubleshooting slack channel I created are about simple stuff that could be easily understood from the most basic docs. And as with the versioning stuff, some progress little by little in that regard would be better than no progress at all.

3. The elephant in the room

Okay, this is the hard part of this little rant of mine, and the one I've been walking on egg shells the most, since I began ruminating about it all in my head. I said above that the project is stable, but more than that, I would say it's actually a bit stale. It's my understanding that much of that comes from a combination of @csswizardry's absence, amplified by our collective admiration and respect for his pet project, and lack of any central decision making authority. I am a fan of Harry myself, and when I say I follow this project from the start, what I mean is that I remember when he posted the first little snippet of what would become it in his blog, the first attempt at the idea of using display: inline-block; instead of float for a grid system, that later he called csswizardry-grids and later would become the layout object. The fork I mentioned before was not of THIS repository, but of the very first one - at the time inuit-css - that he created with a framework in mind, in his own personal github profile. The one even before that one that was a bunch of separated repositories for each fragment.

But his last comment here was around the time I came back to contribute to this version, years ago. As he said in his blog, he moved on in a different direction, and there's nothing wrong with it. This is his framework, but the current @inuitcss/core and a handful of frequent contributors like myself are the ones maintaining it right now.

Also, I do understand none of us are making any money with this project. This is our pet project as much as it is (or was) his, and we love and use and maintain it, donating our time and experience, to help ourselves in our jobs and to give something back to the open source community. But not long ago I saw @csshugs ask for opinions on a merge request and give up and merge it a week or so later because no one even said anything, and that was not an isolated occurrence. Well, this issue itself was mostly ignored for almost 8 months. We need to somehow fix this, either by being a little more present, not in writing new stuff or refactoring code, but in deciding things when things need to be decided, or by deciding on someone to have a final say on this matters.

I've being flirting with forking inuitcss again for some time now, making my version go in a different direction even, and that would be it. It would be easier, and some will say, less shameless, than writing this massive, pedantic even, rant. But if possible I would like to take the project of the guy I admire, the one I've being using for so long and got attached to, to new highs itself, and give it's - not at all small -
following something constantly and consistently better and better.

Well... That's it for now. Again, sorry for the long post, and if I somehow offended someone with this, but those are my takes on some ways this project should go, walking ahead.

[csshugs]

Versioning

I'm all in for releasing 6.0.0 as quickly as possible. @inuitcss/core decided to first merge all the open PRs and then release the stable version. I created a milestone for that to make things a bit more transparent.

Apart from that, I'm with you in increasing the version number in faster steps, maybe not with each individual change, but definitely faster as we do now (well, as you said, we actually never increased the version number at all).

What you said about the develop branch being our main branch is actually true and should be changed. The code people see when they come to our GitHub repo should be the same code they get when they install inuitcss via npm/bower. I vote for changing the default branch back to master, at last when we release 6.0.0.

Documentation

We are aware that the current ‘documentation’ (as code comments) is far away from being optimal. We are actually already working on a documentation site to provide proper docs for inuitcss users. This is not an easy task, obviously and takes a lot of time.

Elephant

I will not comment on this point. Let me (as you mentioned it yourself) just state the obvious: We are all doing this in our free time. When push comes to shove this project has lower priority than our full-time jobs and our families.

@herzinger
Although you declared this post as a rant beforehand, I really want to thank you anyway for your honest feedback!

[anselmh]

@herzinger: Thanks for your in-depth statement here and writing about your frustrations, this is important to hear. I’ll add some of my thoughts to this now:

1. Versioning

You’re right that the framework itself is not in beta. I think it was a good idea though to apply the alpha and beta strategy for the current in-development major version (v6).
Since we had a lot of breaking changes in there and also found a couple of issues that would have affected (=broke) live systems I think this is a good strategy to ensure stable versions work as expected for users.

However, I completely agree that v6 took and still takes us way too long to finish. The scope was never clear so we extened it all the time and didn’t release a first stable version yet. This is not good and causes frustrations, which I totally understand.

I agree we should release v6.0 now with highest priority as a stable version and continue work from there. I don’t like the idea of doing a release with every Pull Request merge and thing this would need several exceptions anyway but I agree that we should release frequently and whenever it makes sense.

2. Documentation

I tend to agree with your here completely but will be honest. I don’t think the current team has the capacity to solve this issue. I think we should come up with a strategy on how we can solve this by aggregating documentation from the inuitcss’ user base and ask for contributions.

3. Decisions

I cannot comment much on that but understand your feelings. I am part of the core team but am not a very active contributor. In fact, I am doing the releases and sometimes a bit of comments here, try to care about the code quality but not much more beyond that. The majority of this project doesn’t work actively on this Open Source project but only when we find time and urge to do so. I don’t think extending the team (at least beyond one or two more people perhaps) will solve anything,
I think we need to become clear on where to go (more discussions like the one happened in the normalize update ticket) and follow these plans. Together with a faster release plan this might improve the situation hopefully.

I think we’re a bit too defensive in asking people outside of the core team for opinions. Pull Requests
and other things can be reviewed by all people. If there are concerns or a core decision required, I think we should continue pinging the team but happy to take a decision if no feedback is given in appropriate time.

[csshugs]

After v6.0.0 is released, I think we can close this one as the only ‘open’ point is documentation, which is covered in #358 as a separate issue.