Skip to content

Commit

Permalink
Rewrite the introduction. Closes #106, closes #95.
Browse files Browse the repository at this point in the history
  • Loading branch information
@domenic
domenic committed May 26, 2013
1 parent 417c016 commit 85e9178
Showing 1 changed file with 4 additions and 6 deletions.
10 changes: 4 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Promises/A+

This proposal clarifies the behavioral clauses of the [Promises/A proposal](http://wiki.commonjs.org/wiki/Promises/A), extending it to cover *de facto* behaviors and omitting parts that are underspecified or problematic.
A *promise* represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its `then` method, which registers callbacks to receive either a promise's eventual value or the reason why the promise cannot be fulfilled.

As with Promises/A, this proposal does not deal with how to create, fulfill, or reject promises.
This specification details the behavior of this `then` method, providing an interoperable base which all Promises/A+ conformant promise implementations can be depended on to provide. As such, the specification should be considered very stable. Although it may be occasionally revised with minor backward-compatible changes to specify newly-discovered corner cases, any large or backward-incompatible changes will be avoided.

This comment has been minimized.

Sign in to view

Copy link
@briancavalier

briancavalier Jun 3, 2013

Member

Hmmm, "of this then method" sounds odd when I read it. How about "of the then method" or "of a promise's then method", or "of a Promises/A+ promise's then method"

This comment has been minimized.

Sign in to view

Copy link
@briancavalier

briancavalier Jun 3, 2013

Member

At the end: "will be avoided" might be too strong. I certainly agree we will try to avoid large and backward-incompatible changes, but if we suddenly discover something tomorrow that leads us to believe we need to make a breaking change, then we'd have to figure out the best way to do it. Presumably, that'd mean a major version rev along with other logistics, etc.

This comment has been minimized.

Sign in to view

Copy link
@domenic

domenic Jun 3, 2013

Author Member

"of the then method" makes most sense to me, given the preceding sentence.

Any suggestions on how to rephrase "will be avoided"? I felt like it wasn't worth discussing much detail on what we would do in that remote eventuality, so I tried covering it with "will be avoided" as opposed to "will never happen."

This comment has been minimized.

Sign in to view

Copy link
@briancavalier

briancavalier Jun 3, 2013

Member

Hmmm, maybe something like:

Although it may be occasionally revised with minor backward-compatible changes to address newly-discovered corner cases, large or backward-incompatible changes will be integrated only after careful consideration, discussion, and testing.

Although now I have the urge to try it in active voice too.

Although the Promises/A+ organization may occasionally revise this specification with minor backward-compatible changes to address newly-discovered corner cases, we will integrate large or backward-incompatible only after careful consideration, discussion, and testing.

Maybe something along one of those two lines?

For a full description of the differences between Promises/A+ and Promises/A, see [Differences from Promises/A](differences-from-promises-a.md).
Historically, Promises/A+ clarifies the behavioral clauses of the earlier [Promises/A proposal](http://wiki.commonjs.org/wiki/Promises/A), extending it to cover *de facto* behaviors and omitting parts that are underspecified or problematic.

## General

A promise represents a value that may not be available yet. The primary method for interacting with a promise is its `then` method.
Finally, we note that Promises/A+ does not deal with how to create, fulfill, or reject promises.

This comment has been minimized.

Sign in to view

Copy link
@briancavalier

briancavalier Jun 3, 2013

Member

"we note that" seems unnecessary, but I won't lose sleep if it stays :) Should we include some reassurance and a link to the resolvers spec so that people quickly get the sense that we are working on creation/fulfillment/rejection? Or would that be a distraction?

This comment has been minimized.

Sign in to view

Copy link
@domenic

domenic Jun 3, 2013

Author Member

Haha yeah we can kill that.

Maybe for now something like

Finally, the core Promises/A+ specification does not deal with how to create, fulfill, or reject promises, choosing instead to focus on providing an interoperable then method. Future work in companion specifications may touch on these subjects, but this specification stands alone.

or something. lost my cohesiveness at the end there.

This comment has been minimized.

Sign in to view

Copy link
@briancavalier

briancavalier Jun 3, 2013

Member

Actually, I think it's pretty good. How about nixing the final "but":

Finally, the core Promises/A+ specification does not deal with how to create, fulfill, or reject promises, choosing instead to focus on providing an interoperable then method. Future work in companion specifications may (hmmm, will?) touch on these subjects.

This comment has been minimized.

Sign in to view

Copy link
@domenic

domenic Jun 3, 2013

Author Member

Yeah, that is nicer. I kind of wanted to emphasize that it's perfectly fine to conform to just the base spec and not any other, as that does give you 80% of the benefits, but we can leave such language for the companion specs themselves perhaps (e.g. "It is not expected that all Promises/A+ implementations will include this extension. If the features of this extension are desired, you should test for them" from promises-aplus/synchronous-inspection-spec#6).

This comment has been minimized.

Sign in to view

Copy link
@briancavalier

briancavalier Jun 3, 2013

Member

leave such language for the companion specs themselves

Sounds like a good plan. In the future, we could have a page that lists all of the P/A+ specs, designating the promises-spec as required, and others as optional.

## Terminology

Expand Down

0 comments on commit 85e9178

Please sign in to comment.