Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

All doc updates forv15.5 #9359

Merged
merged 13 commits into from
Apr 7, 2017
Merged

Conversation

flarnie
Copy link
Contributor

@flarnie flarnie commented Apr 7, 2017

To make this update easy all the doc updates are condensed into this one PR. The smaller other PRs were for ease of review.

This PR includes:

To review please just look at the more recent diffs:

Updating all references and docs on the `React.addons.TestUtils` and the
shallow renderer to refer to the correct targets.

Instead of:
```
const React = require('react');

// ...
React.addons.Testutils
// or

const ReactTestUtils = require('react-addons-test-utils');
```
we now show:
```
const ReactTestUtils = require('react-dom/test-utils');
```

And for shallow renderer, instead of:
```
const shallowRenderer = TestUtils.createRenderer();
```

we now show:
```
const shallowRenderer = require('react-test-renderer/shallow');
```
These flags are used to set arrow links to easily navigate through the
documents. They were wrong or missing in some of the 'add-ons' pages and
this bothered me when manually testing the updates from the previous
commit.
Missed this when updating the docs for the changes to shallow-renderer
in React 15.5.
Thanks @bvaughn for catching this
We should show using the same variable names between code samples.
We should use the same variable name for the same thing across examples.
`renderer` -> `shallowRenderer`.
 - removes link to the docs about `ReactCSSTransitionGroup` and
   `ReactTransitionGroup` from the main navigation
 - updates 'prev' and 'next' pointers to skip this page
 - adds deprecation warning to the top of the page
 - remove references to these modules from the packages README
 - updates 'add-ons' main page to list this as a deprecated add-on
The `React.createClass` method is being deprecated in favor of
`createReactClass`.
It no longer makes sense to have a section for the 'createClass' method
in this page, since it won't be available as a top level method on
'React'.

I initially was going to pull the section about 'createClass' into a
separate page to add under 'addons' but it was short and duplicative of
the 'react-without-es6' docs. So I just linked to those.
I am doing the docs for `context` in a separate commit because that case
was a bit less clear-cut.

We will no longer support `React.PropTypes` as a built-in feature of
React, and instead should direct folks to use the `PropTypes` project
that stands alone.

Rather than retaining the `React.PropTypes` examples and just revamping
them to show the use of the stand-alone `PropTypes` library with React,
it makes more sense to direct people to that project and reduce the
perceived API area and complexity of React core. The proper place to
document `PropTypes` is in the README or docs of that project, not in
React docs.
We use `React.PropTypes` to define the `contextType` for the `context`
feature of React. It's unclear how this will work once `React.PropTypes`
is replaced by the external `PropTypes` library. Some options;

a) Deprecate `context`, either in v16 or shortly after. Seems reasonable
based on the intense warnings against using context that we have in the
docs -
https://facebook.github.io/react/docs/context.html#why-not-to-use-context
**Except** that probably some widely used libraries depend on it, like
`React-Router`.

b) Expect users will use external `PropTypes` library when defining
`contextTypes` and just don't do our `checkReactTypeSpec` against them
any more in v16.

c) Stop masking context and pass the whole context
unmasked everywhere. Worst option, do not recommend.

I went with `b` and assume that, for now, we will get users to use the
external `PropTypes` when defining context. I will update this PR if we
want a different approach.
The plan:
[X] Remove links to 'addons' items from main navigation
[X] Add deprecation notices where appropriate, and update syntax to show
using the separate modules.
[ ] Update other references to 'React.addons' in docs. Coming in next
commit.
--- blocked but coming in future PRs
[ ] Link to a blog post describing the new locations of add-ons in the
deprecation notice on the '/docs/addons.html' page. Blocked until we
actually publish that blog post.
[ ] Move the docs for each add-on to the actual github repo where it now
lives.
[ ] Redirect the old add-ons doc permalinks to the docs in the separate
github repos for those modules.
[ ] Remove the old add-ons doc markdown files from React core docs.
Just misc. places where we referenced the 'addons' feature. All gone!
@flarnie flarnie added this to the 15-hipri milestone Apr 7, 2017
Copy link
Collaborator

@acdlite acdlite left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yay

@acdlite acdlite merged commit 8f72811 into facebook:master Apr 7, 2017
@bvaughn
Copy link
Contributor

bvaughn commented Apr 7, 2017

Thanks @flarnie !

@gaearon
Copy link
Collaborator

gaearon commented Apr 7, 2017

We need to hold off syncing docs until 15.5 is out right?

@acdlite
Copy link
Collaborator

acdlite commented Apr 7, 2017

Yes


## Using React with Add-ons

If using npm, you can install the add-ons individually from npm (e.g. `npm install react-addons-test-utils`) and import them:
You can install the add-ons individually from npm (e.g. `npm install react-addons-create-fragment`) and import them:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to change snippet below to match package name?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! Will submit a follow-up PR.
nice catch

@@ -12,8 +12,6 @@ redirect_from:
- "docs/transferring-props-zh-CN.html"
- "tips/props-in-getInitialState-as-anti-pattern.html"
- "tips/communicate-between-components.html"
prev: rendering-elements.html
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did we remove these? Their ordering seemed important to me.

@@ -3,8 +3,6 @@ id: composition-vs-inheritance
title: Composition vs Inheritance
permalink: docs/composition-vs-inheritance.html
redirect_from: "docs/multiple-components.html"
prev: lifting-state-up.html
next: thinking-in-react.html
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same question here.

@@ -2,8 +2,6 @@
id: conditional-rendering
title: Conditional Rendering
permalink: docs/conditional-rendering.html
prev: handling-events.html
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My thought was that they are no longer part of an ordered navigation - each one is now either a stand-alone package, or deprecated. They soon won't live in the main React documentation. The 'next' and 'prev' links only make sense when they are all part of the set of 'addons', but the concept of the set itself is deprecated.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. I'm a bit confused. These pages (e.g. Conditional Rendering) don't have to do with addons as far as I can see.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right - I was just going through the list of add-ons docs and accidentally updated some others too. Thanks! Fixing in that follow-up PR.

@@ -4,11 +4,15 @@ title: Context
permalink: docs/context.html
---

>Note:
> As of React v15.5 the `React.PropTypes` helper is deprecated, and we recommend using the [`prop-types` library](https://github.com/aackerman/PropTypes) to define `contextTypes`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's change the prop-types link to https://www.npmjs.com/package/prop-types?

flarnie added a commit to flarnie/react that referenced this pull request Apr 7, 2017
In facebook#9359 we accidentally removed
pointers in some doc pages. Putting them back now.
flarnie added a commit to flarnie/react that referenced this pull request Apr 7, 2017
This seems like a more stable place to link to in the 'context'
document.
Based on @bvaughn's feedback in facebook#9359
acdlite pushed a commit that referenced this pull request Apr 7, 2017
* Update example snippet in old 'React.addons' doc page

This makes the example more consistent.

* Add back the pointers in docs that were mistakenly removed

In #9359 we accidentally removed
pointers in some doc pages. Putting them back now.

* Link to npm package instead of github page

This seems like a more stable place to link to in the 'context'
document.
Based on @bvaughn's feedback in #9359
acdlite pushed a commit that referenced this pull request Apr 7, 2017
* `react-addons-test-utils` -> `react-dom/test-utils`

Updating all references and docs on the `React.addons.TestUtils` and the
shallow renderer to refer to the correct targets.

Instead of:
```
const React = require('react');

// ...
React.addons.Testutils
// or

const ReactTestUtils = require('react-addons-test-utils');
```
we now show:
```
const ReactTestUtils = require('react-dom/test-utils');
```

And for shallow renderer, instead of:
```
const shallowRenderer = TestUtils.createRenderer();
```

we now show:
```
const shallowRenderer = require('react-test-renderer/shallow');
```

* Update the 'prev' and 'next' attributes of 'add-ons' docs

These flags are used to set arrow links to easily navigate through the
documents. They were wrong or missing in some of the 'add-ons' pages and
this bothered me when manually testing the updates from the previous
commit.

* Update syntax for instantiating shallow renderer

Missed this when updating the docs for the changes to shallow-renderer
in React 15.5.

* Fix pointers in addons docs

Thanks @bvaughn for catching this

* Make example of shallow renderer more consistent

We should show using the same variable names between code samples.

* Make names in example even more consistent

We should use the same variable name for the same thing across examples.
`renderer` -> `shallowRenderer`.

* Update docs to deprecate React<CSS>TransitionGroup

 - removes link to the docs about `ReactCSSTransitionGroup` and
   `ReactTransitionGroup` from the main navigation
 - updates 'prev' and 'next' pointers to skip this page
 - adds deprecation warning to the top of the page
 - remove references to these modules from the packages README
 - updates 'add-ons' main page to list this as a deprecated add-on

* Update `React.createClass` to `createReactClass` in the docs

The `React.createClass` method is being deprecated in favor of
`createReactClass`.

* Remove 'React.createClass' from top level API docs

It no longer makes sense to have a section for the 'createClass' method
in this page, since it won't be available as a top level method on
'React'.

I initially was going to pull the section about 'createClass' into a
separate page to add under 'addons' but it was short and duplicative of
the 'react-without-es6' docs. So I just linked to those.

* Remove *most* `React.PropTypes` from the docs

I am doing the docs for `context` in a separate commit because that case
was a bit less clear-cut.

We will no longer support `React.PropTypes` as a built-in feature of
React, and instead should direct folks to use the `PropTypes` project
that stands alone.

Rather than retaining the `React.PropTypes` examples and just revamping
them to show the use of the stand-alone `PropTypes` library with React,
it makes more sense to direct people to that project and reduce the
perceived API area and complexity of React core. The proper place to
document `PropTypes` is in the README or docs of that project, not in
React docs.

* Update `context` docs to not use `React.PropTypes`

We use `React.PropTypes` to define the `contextType` for the `context`
feature of React. It's unclear how this will work once `React.PropTypes`
is replaced by the external `PropTypes` library. Some options;

a) Deprecate `context`, either in v16 or shortly after. Seems reasonable
based on the intense warnings against using context that we have in the
docs -
https://facebook.github.io/react/docs/context.html#why-not-to-use-context
**Except** that probably some widely used libraries depend on it, like
`React-Router`.

b) Expect users will use external `PropTypes` library when defining
`contextTypes` and just don't do our `checkReactTypeSpec` against them
any more in v16.

c) Stop masking context and pass the whole context
unmasked everywhere. Worst option, do not recommend.

I went with `b` and assume that, for now, we will get users to use the
external `PropTypes` when defining context. I will update this PR if we
want a different approach.

* Remove 'addons' items from left nav, and deprecate 'addons' doc page

The plan:
[X] Remove links to 'addons' items from main navigation
[X] Add deprecation notices where appropriate, and update syntax to show
using the separate modules.
[ ] Update other references to 'React.addons' in docs. Coming in next
commit.
--- blocked but coming in future PRs
[ ] Link to a blog post describing the new locations of add-ons in the
deprecation notice on the '/docs/addons.html' page. Blocked until we
actually publish that blog post.
[ ] Move the docs for each add-on to the actual github repo where it now
lives.
[ ] Redirect the old add-ons doc permalinks to the docs in the separate
github repos for those modules.
[ ] Remove the old add-ons doc markdown files from React core docs.

* Remove references to `React.addons` from docs

Just misc. places where we referenced the 'addons' feature. All gone!
acdlite pushed a commit that referenced this pull request Apr 7, 2017
* Update example snippet in old 'React.addons' doc page

This makes the example more consistent.

* Add back the pointers in docs that were mistakenly removed

In #9359 we accidentally removed
pointers in some doc pages. Putting them back now.

* Link to npm package instead of github page

This seems like a more stable place to link to in the 'context'
document.
Based on @bvaughn's feedback in #9359
@gaearon
Copy link
Collaborator

gaearon commented Jul 11, 2017

Here is what the PropTypes deprecation looks like in the docs today:

screen shot 2017-07-11 at 13 45 27

The (unintentional) bold is super scary, and there is no mention of the codemod. Somebody reading this will have no idea it's possible to do the conversion automatically.

Let's make sure that we preview changes to the docs in the future (by running the local server), and that new mentions of deprecations link to blog posts that link to codemods.

@gaearon
Copy link
Collaborator

gaearon commented Jul 11, 2017

(I merged a PR to fix this but let's keep in mind for future deprecations.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants