New principle: A Promise represents completion or a value, not a callback (#342)

[jan-ivar]

Fixes #342.

---

Preview | Diff

[martinthomson]

This LGTM. Time to ask the rest of the TAG to review.

[jan-ivar]

Thanks @martinthomson!

I appear to be unable to add reviewers in this repo, so hopefully there's a process for that?

[LeaVerou]

Overall this seems a bit esoteric, and I agree with @jyasskin that the title as stated is not always true. I think the examples need some work to establish what should or shouldn't be done, otherwise this principle only makes sense to those who already understand it.

[jan-ivar]

Feedback incorporated. Thanks!

[jan-ivar]

We could also shorten it further to: "A Promise represents completion, not a callback" — thoughts?

[martinthomson]

I like this. I think that the one thing that might be added

If an API depends on setting up temporary conditions then invoking the caller,
that is a good reason to use a callback rather than a promise.

[jan-ivar]

@LeaVerou does this look better?