Chai: Chai Roadmap

[keithamus]

TL;DR

Over the next few versions we're going to try to do the following:

• Refactor messages to support advanced template strings (per chaijs/chai#393)
• Refactor plugin declarations to support new interfaces (per chaijs/chai#117)
• Split out chai codebase into various modules
• Turn chai into a metapackage which combines these modules

Refactor Messages

@svallory has done some excellent work into refactoring the message syntax for chai assertions. This will make writing plugins simpler, as the need for message variants is removed.

See chaijs/chai#393 for more.

Refactor plugin declarations

Right now the plugin system is simple to use, and has lead to a successful plugin community. But it could be better.

Assertions should declare the flags they use in an up-front manner, allowing deeper introspection for interfaces. This will allow us to put effort into making interfaces which are pain points for the community - such as an assert interface that works with <=IE8, and expect/should interfaces which use method assertions over property assertions.

Two of the biggest causes of fragmentation of chai users is due to low browser support, and the property assertions - which spawns off codebases like the following:

• hapijs/code
• rowanmanning/proclaim
• moll/js-must
• wrumsby/ristretto

While we can't be all things to all people, some of these libraries exist purely
because Chai has failed them, and so we see a lot of duplication of effort.

Some of this has been discussed in chaijs/chai#117.

Split out chai codebase into various modules

We've been putting efforts into splitting chai out into smaller modules, and it's been working well - but I think we can go further. The way I see things, we can split chai into the following:

• chai-core (plugin loader interface, lib/assert, lib/chai/utils.[add/overwrite]*.js)
• chai-common-assertions (existing assertions, lib/chai/core/assertions.js)
• message-formatter (lib/chai/utils/getMessage.js, and @svallory's work)
• checkError (complex logic within lib/chai/core/assertions.js .throw assertion)
• loupe (lib/chai/utils/inspect.js, old code exists as loupe, but needs updating and removing from chai proper)
• AssertionError (already modularised as assertion-error)
• type-detect (already modularised as type-detect)
• pathval (lib/chai/utils/getPathInfo, old code exists as pathval, but needs updating and removing from chai proper)
• interfaces
  
  
  
  • assert (lib/chai/interface/assert)
  
  
  • expect (lib/chai/interface/expect)
  
  
  • should (lib/chai/interface/should)
  
  
  • assert-legacy (potential new interface for older browsers)
  
  
  • expect-method ("jshint friendly expect")
  
  
  • should-method ("jshint friendly should")
  
  

Becoming more modular, we can also hope to facilitate some new and interesting use cases of our work, such as described in chaijs/chai#346

Chai metapackage

With modules pulled out of the main chai codebase, we can effectively turn the chai package into a metapackage of the rest of chai. It'll still be a first class part of chai, and we'd funnel all issues to this - but by having discrete modules for each part, we give the community a chance to pick and chose elements. We can innovate in areas, like having a chai-lite module which can be used in older browsers, while chai proper can innovate upon evergreen browsers.

Roadmap:

Based on the above, I see the roadmap as follows:

3.0.0

• [x] Move type-detect into its own library (thanks @davelosert!).

  4.0.0

• [x] Move pathval into its own module (thanks @lucasfcosta!). [Issue: #737]

• [x] Improve deep-eql for ES6 and more. [#837]

• [x] Move checkError into its own module (thanks @lucasfcosta!). [#683]

  5.0.0

• [ ] Switch to new declarative plugin syntax (where plugins define the flags they support upfront) [WIP #585]

• [ ] Switch to new chai message formatting

• [ ] Move loupe into its own module. [WIP]

  5.1.0

• [ ] Trial new interfaces, assert-legacy, expect-methods and should-methods.

• [ ] Move chai-core into its own module.
• [ ] Move chai-common-assertions into its own module.

[boneskull]

Chai rules. you guys rule. keep kicking ass please.

[keithamus]

:heart: thanks @boneskull :smile:

[sukrosono]

sounds good, but why build failing?

[keithamus]

mostly due to flakiness from SauceLabs.

[lucasfcosta]

Hello everyone, so I was talking with @vieiralucas tonight about the 4.x.x release and I think it's about time for us to release that.
I'm not trying to hurry any of you, but maybe we could postpone the loupe module migration for a next release. We've got a lot of nice things to release and, for what I've heard our users can't wait for that 😄

So, I was thinking about meeeting @vieiralucas in a café this weekend and getting every pending thing done, which currently is this:

• [x] Finish the 4.x.x migration guide
• [ ] Publish pathval and refactor Chai's core to use it (depends on chaijs/pathval#23)
• [ ] Publish a canary version with those changes (as per #751)

Also, I see that there's a lot of work waiting to be merged on the deep-equal, currently, as @keithamus said, it's on the final draft stage but the benchmarks show it is slower than lodash and node's assert. Would you guys like to try solving those performance issues before releasing or would you like to release 4.x.x without that? Also, we can review that module and merge it anyway (if it's correct) and only then address the performance issues.

Also, I'd like to reiterate I don't want to hurry anybody, feel free to do things at your own time, that's the beauty of Open Source 😄

Me and @vieiralucas were just thinking about using the free time we've got this weekend to get some things done, but we would like to hear your opinions first.

Please let me know if you think I'm being too hasty, this is just my 2cents.

Oh, and thanks again for the awesome work we've been doing since 3.5.0 👍

[meeber]

This sounds good, and I agree about postponing loupe for a future release. However, I'll have to defer to @keithamus regarding the state of deep-equal. I'm not too connected on the topic in general, and I haven't reviewed the big PR yet.

Curious: Are there any existing deep-equal libraries that fulfill all of our needs? If so, has there been any consideration about using one of them, at least until we've worked out all the kinks in ours? Something to ponder if it looks like it's going to take substantial time and effort to reach a release-ready state.

[keithamus]

I agree with pushing loupe until a later release. Edited the OP to reflect that. I also think that loupe, as part of the 5.0.0 release fits well with the other features - a new plugin system and new error message formatting.

I'd like to see deep-eql pushed into chai 4, partly because it is nearly done but more importantly - it is a big breaking change, but will solve some pretty pressing issues: #332, #608, #644, #793.

Sadly I'm very busy in my personal life which has limited the time I can put into this. I'm going to try to put some more time into fixing up deep-eql so that performs well, I don't want to hold up the release any longer but, again, I feel like it's super important we get it into 4.0.0.

Aside to @meeber; our (new) deep-equal implementation has some very important features for us which others don't have; most importantly overriding the comparator which will enable #644

[lucasfcosta]

@keithamus don't worry, you are always doing great things for chai, you are the one which got us involved here and made this project such an awesome one to start contributing! You rock!
Also, me and @vieiralucas can take a look on that and help you with deep-eql's performance.

[vieiralucas]

@keithamus I would like to reinforce what @lucasfcosta said above that we don't want to hurry up anyone, specially you. Please don't feel pressured to do anything.

[lucasfcosta]

@keithamus @meeber @shvaikalesh @vieiralucas
Hello everyone!
So, I noticed we've got plenty pending PRs, thus I think maybe we should start cutting things off for the 4.x.x release, specially breaking changes.

IMO we could start accepting breaking PRs into a 5.x.x branch and add only bugfixes and small changes to master. Focusing on getting the next major version out would greatly help us getting feedback from users and therefore (IMO) should be prioritized.

Let me know if you disagree and please share your thoughts, I just want to make sure we're all on the same page :smile:

[keithamus]

I think we're at the right time to release a canary now - with the proviso that I still really want to get deep-eql into 4.0, so we'll release a second canary when that work is done.

[meeber]

Agreed with @keithamus. Let's go ahead and release a canary version without deep-eql but make it clear in the announcement that there's still one more big change to come in a subsequent canary version.

[lucasfcosta]

@keithamus I totally agree.
Is pathval's refactor going to be included on that first version?
I feel like that would be very simple to do since all it's needed is to add it as a dependency and remove the old code from utils in order to start using the new dependency.

[keithamus]

Yes, yes pathval will be too. I need to add the token, been very busy IRL and it keeps getting pushed back. Sorry for this.

[lucasfcosta]

@keithamus no need to be sorry! I just wanted to know if we would include that because if we will I can start working with the module installed locally.

Chai is good because it's made with love, please do it only when you have time, there's no need to rush :heart:

[lucasfcosta]

@keithamus I think we can tick the deep-eql task and remove the WIP tag.
Are you guys ready for a canary release? 🎉
Have we got anything that isn't on the migration guide?

cc @vieiralucas @meeber @shvaikalesh

[meeber]

Ready!

[vieiralucas]

Gogogo

[meeber]

@lucasfcosta Since we're doing a manual release this time, does only @keithamus have the permissions to publish a new version to npm? Or...? No rush, just want to make sure we're not all waiting for someone else to do something :D

[keithamus]

@meeber I have invited you and @lucasfcosta to a shared lastpass folder, which provides you with all the passwords for the chaijs-bot which can publish releases. Perhaps I got your email wrong?

[lucasfcosta]

@keithamus I have nothing in "folders shared with me". My registered email is [email protected], maybe you did a typo or something like that.

[keithamus]

@lucasfcosta okay will sort it out shortly.

[lucasfcosta]

@keithamus @meeber @shvaikalesh Hello everyone, so, now that I've got access to the shared folder, I talked to @keithamus this morning and he authorized me to release it, so, since I'll meet @vieiralucas tonight at college we will take some time to do it together and make sure everything goes right.

The tag's name will be canary, is everyone okay with that? Please let me know if you want to schedule another date for a release or anything like that. Thanks everyone 😄

[meeber]

I'm fine with canary. So 4.0.0-canary.1 will be the first prerelease version?

[keithamus]

If you also publish with the dist-tag canary the users can install with npm i chai@canary.

[lucasfcosta]

Hello everyone, we've got something pretty wrong going on, me and @vieiralucas were following the guidelines described on our CONTRIBUTING.md file and we were extra careful when creating tags and etc, but apparently for some reason a bot or Travis published it when we tagged the latest commit on master as 4.0.0-canary.1.
Is there anyone with any reasonable solution for this?

Tagging @keithamus @shvaikalesh @meeber for extra urgent issue.

PS.: Sorry for that 😓

---

EDIT: Solved thanks to Laurie Voss

WE DID IT!!! 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉

[vieiralucas]

🎉 🎉 🎉 🎉 🎉

Does anyone have an idea on how it got published?

[lucasfcosta]

Ping @keithamus @vieiralucas @meeber @shvaikalesh
Hi friends! I've noticed we slowed a bit during the last month and I think that's because we have already got everything done for 4.0.0.

Is there anything preventing us from releasing 4.0.0 out in the wild? It has been available under the canary tag for quite some time and I think the only thing that's preventing us from doing that is #890.

Am I right? What would you think we should do?

[keithamus]

I'd be happy for us to go ahead and release 4.0. IMO the quiet period was really just to let the dust settle on the Canary release of 4. I think that's the case now. Does anyone want to pick up the PR for making the 4.0 release?

[shvaikalesh]

I think plugins issues mentioned in #890 (btw awesome work outlining them, @meeber!) are rather major so I believe they should be addressed before 4.0 release.

[lucasfcosta]

I agree with @shvaikalesh.

Let's solve those plugin issues and release 4.0.0! Also, I can release it when the time comes but I'd like to make sure the auto-release by Travis is disabled in order to avoid having the same problems we had last time.

[meeber]

Because of the extent of changes since the initial canary release, particularly in regard to proxies, I'd like to have a 4.0.0-canary.2 release for a short, predetermined amount of time prior to our official release. 1 week would be sufficient I think.

Therefore, I propose that we merge these last few PRs that were submitted today, then release 4.0.0-canary.2, and then after 1 week (assuming no major issues), release final v4.

[lucasfcosta]

I agree with @meeber. I'll finish #899 this weekend, if you want to wait for it before releasing 4.0.0-canary.2 it will be done before sunday.

Anyway, would any of you like to release it? I'm a bit scared by what happened last time, but I wouldn't mind doing it if we turned the auto-release on travis off.

[meeber]

I think we can wait for that PR. And yeah, it does seem like these lines were the likely culprit with the inadvertent auto-release last time.

[lucasfcosta]

Hey folks, so, how do you feel about releasing 4.0.0-canary.2 this week?

[meeber]

There's a few bug fixes and a major doc update I want to squeeze in for canary 2. I think I can have them ready by this weekend.

[keithamus]

@meeber @lucasfcosta @vieiralucas @shvaikalesh how are we all with this now? I know we said about a canary.2 release back in Jan, am I right in saying #920 is the only one we want to get out for this? If that's the case I think we should jump right to a rc release once #920 is merged, and give it 2 weeks of user testing, then release a 4.0 final. Everyone behind this idea?

[meeber]

@keithamus Also looking to merge #947!

[lucasfcosta]

@keithamus sounds like a good idea to me! It's about time we release a new version. I've been using 4.0 recently and I couldn't find any problems until now.

[lucasfcosta]

Hello everyone!
So, what about releasing 4.0? IMO canary has been out for long enough for people to detect any critical bugs.
As I've said above, I've been using it myself in the last few months and couldn't find any problems.

What are your opinions on this?

[meeber]

@lucasfcosta Agreed. Let's merge #964, regenerate index.js, and release.

[keithamus]

Right, we're ready for a 4.0 release. Who wants to make the PR? It will involve uncommenting the commented out travis lines, and running make release-major. Anyone is welcome to take this on!

[lucasfcosta]

I'll meet @vieiralucas tonight in college so we can do that and prepare all the stuff we need to get this out.

Also, do we need to update anything in the 4.0 migration guide? I'll take a look at it to make sure it is updated.

[lucasfcosta]

Hey everyone, me and @vieiralucas have had problems with the make task that does a major release.

It was trying to bump the version number on the lib/chai.js file too, which has been updated to get it from package.json, so the command was failing.

I made a PR for that. As soon as we get that merged I'll make the PR for the release.

Please see #967.

I'll spend tonight updating the migration guide, let's make sure it is complete before releasing, by the way.

EDIT: Migration guide updated! 🎉

[demurgos]

Hi, I know that many people (including some maintainers) would like first-class support for async primitives (async functions, Promises) into chai core. Does it still fit into the roadmap (with the plan to transform chai into a meta-package)?

[lucasfcosta]

@keithamus I was thinking that maybe we could close this and keep all our roadmap into the project board due to the future plans, otherwise this issue might just get bigger and bigger and it will be probably hard to read, reference and have a scope which is too broad.

What does everyone think?

[keithamus]

Yes absolutely. Let's close this. Perhaps we can make a change to the README which points to the roadmap project board.. At any rate there is not much more info in this issue that isn't covered on the roadmap project board.