Ideas for UI-Bootstrap's vision/principles

[chrisirhc]

(Note: This is a discussion, and I thought it's quite different from code conventions so I didn't mention this in #1490)

I was thinking about this the other day, we may need some grounding principles for this repository to guide decisions in adding new features or directives.

I was hoping to start a wiki page that would hold some of these thoughts (open to discussion and I'm happy to add more):

• Simple-first but extensible
  • Support basic use cases easily
  • Allow customizations only if they don't complicate the basic use cases
  • Expose API (through directive controller and/or services) for rare/complex use cases
• Promote and encourage usage of components in the template, the Angular way

As the API stabilizes, I think it becomes more reasonable to ask users to write their custom directives, that extend Bootstrap's directives, to support custom functionality.

Contrast this to asking users to run their own patched/forked version of the repository, I think I much prefer asking them to write and maintain directives that extend Bootstrap's directives.

It may also make sense to keep a library of snippets of these custom directives in the Wiki so that new users can browse through ways to use the API.

Before this can happen, we should migrate into semantic versioning. This helps users to identify which versions will break the API.

[pkozlowski-opensource]

@chrisirhc you must be reading my mind :-) I also wanted to start a discussion about next steps in this project. I think that the principles you are rising here are very important and I do agree with them. Also huge +1 for semantic versioning, currently people got no idea what a given version contains...

Now, I think those topics are becoming more and more important as we will be inevitably heading towards the 1.0 release and API stabilization. But there are few other things that I would like to do before 1.0:

• AngularJS 1.2.x support
• add missing functionality (templates for tooltips / popovers, manual triggers, missing directives)
• stabilize the API (add prefixes, directive usage, interface to templates, controllers)
• accessibility
• bug fixing
• project build / lifecycle changes (sem versioning, split the web site into demo and reference documentation)

I do agree that we should keep those directives as simple and as extensible as possible instead of trying to embed every possible option behind a configuration setting.

@chrisirhc I'm just dumping my brain here and I guess I'm starting a topic that is a bit broader compared to what you wanted to discuss. But yeh, I think we are getting o the point where we should think about the future of this project.

[chrisirhc]

@pkozlowski-opensource no worries, please dump everything that's on your mind 👍 .

I guess some todos for issues tracking:

• Add issues for each bugfix for stabilizing the API and assign 1.0 milestone
• Assign 1.0 milestone to functionality that's required for 1.0

We can always do add 0.10 milestone later if we're not quite ready for 1.0 as the next release (which I don't think we are). Some issues can later be moved between the 1.0 and 0.10 milestones.

[pkozlowski-opensource]

Yeh, I agree that we are not ready for 1.0 yet, but we should start working towards it. I'm going to review existing issues and open new ones over the weekend, but @angular-ui/bootstrap, please do the same.

[chrisirhc]

Perhaps this is a better place for discussion on #1564.

Taken from #1564

@bekos:

I agree that we don't know and cannot tell what is rare or not. The reason of adding this kind of directives is to keep the library fast and the organization of code simple. I disagree that the users that are using this library are looking for something simple and I am totally sure that many of them will not know or even bother to go to a wiki to search for a custom directive and manually add it to their application. Most of the times, they just pass and look for another alternative that supports it out of the box.

So, IMO this is another discussion we should take in the near future (cc: @pkozlowski-opensource ) about how far we want to go :-)

Now, in terms of consistency, I believe that all optional directives should be evaluated as boolean for the same reasons as above. If this directive makes the library bloated or unmaintainable I also agree to remove, but leaving out a feature for the shake of 15 LOC added is not possibly the best.

I understand your point of view. I just wanted to say that this feature isn't really about the 15 lines of code. What I'm saying is that this 15 lines of code (or more) will have to be added in the future for future features every time such a need arises.

I have to disagree about your point about users of library not looking for something simple. In my opinion, advanced uses of a library should be allowed, but not encouraged via documentation. The library should contain one simple use case that shows users: "here's the main use case and if it's not enough, you now know how to override this behavior to customize it".

By adding a feature there are three main things that have to be considered:

• New feature adds more documentation to read for the simple user
  This dilutes the main use case with advanced use cases. This may also confuse new users as they're led to wonder what's the main use case of the directive.
• New feature introduces inconsistencies to existing or future code
  For example, a new feature in one component indicates a missing feature of another component. Some features
• New feature adds more lines of code to maintain

If we have a stable API, users looking for advanced uses of the library should maintain their own complex use of it.

With regards to users not bothering to search or wiki, this is a problem that needs to be solved through other means such as adding links in the documentation to the wiki.

[bekos]

@chrisirhc The point I want to make is that atm, at least, we decide if a feature is worth to be added or not. If we believe that a feature is not worth it, we don't add it.

Having said that, I believe that the problem of simple and complex use case should also be solved by other means, such as demos and links, and documentation API. For example, take a look at the datepicker of the Jquery UI. From the demo you can say that this is a simple datepicker, and in fact used by all kind of developers in 99% of the applications. Then look at it's API on the right bottom corner. Who knows that it has around 50 options and 10 methods? Only the people who wanted to use it in a complex case.

Again my point, is that a library should be fast, reliable, consistent, maintainable and feature full. It's the documentation's and demo's site responsibility to make the distinction to the users. Our job is to add code that conforms to the first points.
Also, who is going to maintain the links to the custom directives? If I change the progressbar directive who will be responsible to update the code for the max directive? Us again, right? or is it the only thing that we want to do, is to provide a base and then tutor others how to extend it in their application. If so, then our role is to start removing things from the library instead of adding and improving.

@shaungrady What means simplicity in implementation? The discussion is not whether the implementation of the feature is simple or not, but whether we want to add the feature or not. Simplicity and implementation are things easier said than done.

[chrisirhc]

@bekos Okay, I understand that in our discussion on that commit, we're weighing whether a feature is worth it. I'm starting a discussion with regards to that thought here.

I'm thinking about this library from the perspective of creating a stable API so that we can go ahead into semantic versioning. Just as a case study, assume we have a feature we do want to implement.

First, as an API, this feature should be possible. This means users don't need to copy/paste and re-implement the whole directive to get the feature.

Second, I feel that because this library is called Bootstrap, it aims to lay a groundwork for users to extend upon. This is how I personally feel about this library, and hence, this discussion thread, I want to gather feedback about the vision of this project.

This is especially true for a feature that can be implemented in a number of ways which users may not agree upon. In such a scenario, it's perhaps better to allow the users to write their own implementation but our API must allow that.

As a side note, I feel that Angular directives are a little different from jQueryUI widgets. jQueryUI widgets need to be redefined to extend their functionality while in Angular, you can change behavior of an existing controller. Hence, it's definitely understandable that they had to provide the many options that they have. I also feel that AngularJS users are more likely to need to learn to write directives as opposed to users of jQueryUI needing to write widgets.

I agree that the problem of simple vs complex use case can be solved through improving the documentation and demos.

[bekos]

@chrisirhc I agree that this is a more general discussion. Again, my opinion is that every feature is a special case and as such shall be examined.

Even when we move to semantic versioning, the question will rise again, whether we want to add a feature or not.
I agree with the principle that if something has contradicting behavior should be left out of the core, and just provide the means to easily adopt in each use case (ie the dismissAll API). For other cases we want to add to core, we should do our best to provide a configurable or not option that does not "harm" the simple cases.
For me this is the fun of working on this project. Implementing and improving things... and having such discussions also :-)

I also agree to move logic to controller, add watchers only if needed etc that has all the advantages that you said and is something that we try to do anyway. This also falls into the previous section of providing an extensible API.

Change is not going to happen from one day to the other. If something added in a directive "reveals" that something is missing from another, then we should add the second, not hide the first. The only issue is the time that things are going to align. If we were working solely on this project, that would be another discussion!

I am going to sleep on our discussion now :-)

PS I didn't compare jqueryUI with angular, it was just an example how you can hide complexity from a simple user.

PPS I think this library is called Bootstrap because it relies on Bootstrap's markup and CSS :P It was just an inch away from called "Angular Widgets"

[mvhecke]

Today I noticed there are some inconsistencies in the attribute names of directives, things can get a bit confusing for people who are new to this. For example in the accordion directive the attribute for disabling (#1126 in progress) things will be called is-disabled, but when I take a look at tabs it's called disabled. Although don't promote introducing breaking changes, but this might be a good thing to discuss before hitting 1.0. I'm curious what you guys think about these naming conventions.

[bekos]

@Gamemaniak Agree. An is- prefix may be a convention for all boolean attributes.

[Foxandxss]

@pkozlowski-opensource What happened with the idea of making this directives generic? To work with foundation, etc. It is still in mind? If we could make that happen, that would be 3 times awesome.

[pkozlowski-opensource]

@Foxandxss this would be ideal but it is not so easy in practice... And I feel it will be even less practical when we use $animate... But yes, this is an ideal to strive for.

@Foxandxss we are having a hangout tomorrow evening (UTC) to discuss next steps for this project. Would you like to take part in it?

[Foxandxss]

@pkozlowski-opensource Would love to. I have no idea of how that works but you could explain to me (and maybe pay a visit to the IRC? :P).

[chrisirhc]

@pkozlowski-opensource is that because of the use of the animation class names?

[pkozlowski-opensource]

@chrisirhc I'm afraid so. In my mind the ideal solution would consist of having CSS class names in templates only, but I'm not sure it is possible in practice. We might reach out to AngularJS guys, I'm sure they will be keen on helping us as this is a more generic problem - how to use AngularJS directives with 3rd party CSS and $animate.

[Foxandxss]

@pkozlowski-opensource So what's the hour for the hangout? :)

[ajoslin]

@Foxandxss in 5 minutes. Email me if you get this in time (email on my gh profile) and we can invite you.

[Foxandxss]

To not open an issue just yet, I think we really need to open an issue with all the tasks needed to release a new version. There are a couple of bugs, smaller and bigger which are already fixed in master and well, there is a big need of a new release so we should start focusing on that ASAP.

@angular-ui/bootstrap WDYT

[chrisirhc]

I think we need to be better about milestones, as that's usually the way to handle releases. Once all issues within a milestone is resolved, a release can be made.

[Foxandxss]

Yeah, angular style, I like that.

[Foxandxss]

Closing this. Not an actual issue and we talk about this stuff every day on our slack :)