Porting over glossary content from old repository #153

mrscobbler · 2017-10-12T23:05:14Z

Adding glossary content to new repo

reactjs-bot · 2017-10-12T23:08:56Z

Deploy preview ready!

Built with commit 8e9703d

https://deploy-preview-153--reactjs.netlify.com

alexkrolick · 2017-10-13T00:25:40Z

content/docs/reference-glossary.md

+## ES6/ES2015
+ ES6 AKA ES2015 is the current version of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, and `let` and `const` statements. 
+
+## Compilers


Maybe mention "transpiler" as another term for this section

I think we decided that we were going to avoid using the word transpiler because it causes confusion. See comment here from @gaearon: facebook/react#8199 (comment)

bvaughn

Thanks a ton for putting this together! Looks great!

I added some feedback. Would like to know your thoughts!

bvaughn · 2017-10-16T05:37:56Z

content/docs/reference-glossary.md

+
+
+## ES6/ES2015
+ ES6 AKA ES2015 is the current version of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, and `let` and `const` statements. 


Maybe we can changing the wording "current version" since ES 7/2016 was finalized in June 2016 with exponentiation operator and Array.prototype.includes and ES 8/2017 was finalized in June 2017 with async / await.

I can make the wording a little better so that it can include future versions of ES7/8/9 etc.

bvaughn · 2017-10-16T05:40:32Z

content/docs/reference-glossary.md

+ ES6 AKA ES2015 is the current version of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, and `let` and `const` statements. 
+
+## Compilers
+A JavaScript compiler takes JavaScript code, transforms it and returns JavaScript code in a different format. The most common use case is to take ES2015/ES6 syntax and transform it into syntax that browsers are capable of interpreting. Babel is the compiler used with React. 


nit: What do you think about adding the word "older"?

transform it into syntax that older browsers are capable of interpreting

Great! Will make the change.

bvaughn · 2017-10-16T05:41:46Z

content/docs/reference-glossary.md

+CDN stands for Content Delivery Network. CDNs deliver cached, static content from a network of servers across the globe. 
+
+## JSX
+JSX is a syntax extension to JavaScript. It is similar to a template language. JSX gets compiled to React.createElement() calls which return plain JavaScript objects called 'React elements'. To get a basic introduction to JSX [see the docs here](https://facebook.github.io/react/docs/introducing-jsx.html) and find a more in-depth tutorial on JSX [here](https://facebook.github.io/react/docs/jsx-in-depth.html)


nit: Maybe wrap "React.createElement()" with ticks so it's formatted React.createElement()?

bvaughn · 2017-10-16T05:44:48Z

content/docs/reference-glossary.md

+JSX is a syntax extension to JavaScript. It is similar to a template language. JSX gets compiled to React.createElement() calls which return plain JavaScript objects called 'React elements'. To get a basic introduction to JSX [see the docs here](https://facebook.github.io/react/docs/introducing-jsx.html) and find a more in-depth tutorial on JSX [here](https://facebook.github.io/react/docs/jsx-in-depth.html)
+
+React DOM uses camelCase property naming convention instead of HTML attribute names.
+For example, class becomes className in JSX, and tabindex becomes tabIndex.


How do you feel about this wording instead?

React DOM uses camelCase property naming convention instead of HTML attribute names. For example, tabindex becomes tabIndex in JSX. The attribute class is also written as className since "class" is a reserved word in JavaScript.

Sounds good!

bvaughn · 2017-10-16T05:46:14Z

content/docs/reference-glossary.md

+For example, class becomes className in JSX, and tabindex becomes tabIndex.
+
+## [Elements](https://facebook.github.io/react/docs/rendering-elements.html)
+React elements are the building blocks of React applications. One might confuse elements with a more widely known concept of "components". Elements are what components are "made of". An element describes what you want to see on the screen. React elements are immutable.


What do you think about this wording?

Elements are a template that components are created from.

I'm not sure it's great. I just thought "made of" might be a bit vague.

I'll work on the wording a little bit -- I copied that wording from this page here: https://reactjs.org/docs/rendering-elements.html

Perhaps we should change the wording there too?

Gotcha! A lot of these wording things are subjective. I know for example that Dan and I often have slightly different preferences when it comes to wording, so particularly for comments like this- I don't feel super strongly about it.

If you think the wording can be improved though, let's change it in both places 😁

bvaughn · 2017-10-16T05:52:57Z

content/docs/reference-glossary.md

+A component's `state` is a snapshot of the data contained in a component. `props` and `state` are different: `state` is user-defined, `props` are received from a parent component.
+
+## [Lifecycle Methods](https://facebook.github.io/react/docs/state-and-lifecycle.html#adding-lifecycle-methods-to-a-class)
+Lifecycle methods are custom functionality that gets executed during the different phases of a component. There are methods available when the component gets created and inserted into the DOM ([mounting](https://facebook.github.io/react/docs/react-component.html#mounting)), when the component updates and when the component gets unmounted or removed from the DOM. 


super nit 😆 oxford comma!

when the component updates, and when the component gets unmounted or removed from the DOM.

Will add! :)

bvaughn · 2017-10-16T05:58:18Z

content/docs/reference-glossary.md

+Lifecycle methods are custom functionality that gets executed during the different phases of a component. There are methods available when the component gets created and inserted into the DOM ([mounting](https://facebook.github.io/react/docs/react-component.html#mounting)), when the component updates and when the component gets unmounted or removed from the DOM. 
+
+ ## [Controlled](https://facebook.github.io/react/docs/forms.html#controlled-components) vs. [Uncontrolled Components](https://facebook.github.io/react/docs/uncontrolled-components.html)
+React has two different approaches to dealing with form inputs. An input form element whose value is controlled by React is called a *controlled component*. An *uncontrolled component* is an input that is just like any normal input we would use outside of React. When a user inputs data into a form field (an input box, dropdown, etc) the updated information is reflected. 


I think we could add a little more context here. What do you think about something like...

React has two different approaches to dealing with form inputs.

An input form element whose value is controlled by React is called a controlled component. When a user enters data into a controlled component a change event handler is triggered and your code decides whether the input is valid (by re-rendering with the updated value). If you do not re-render then the form element will remain unchanged.

An uncontrolled component works like form elements do outside of React. When a user inputs data into a form field (an input box, dropdown, etc) the updated information is reflected without React needing to do anything.

Will change!

bvaughn · 2017-10-16T05:59:02Z

content/docs/reference-glossary.md

+React has two different approaches to dealing with form inputs. An input form element whose value is controlled by React is called a *controlled component*. An *uncontrolled component* is an input that is just like any normal input we would use outside of React. When a user inputs data into a form field (an input box, dropdown, etc) the updated information is reflected. 
+
+## [Keys](https://facebook.github.io/react/docs/lists-and-keys.html) 
+ A "key" is a special string attribute you need to include when creating lists of elements. Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside an array to give the elements a stable identity.


I would maybe say "when creating arrays of elements" to avoid confusion with HTML lists (eg <ul>, <ol>) that don't necessarily require keys (depending on how you render the list items).

bvaughn · 2017-10-16T06:02:56Z

content/docs/reference-glossary.md

+ A "key" is a special string attribute you need to include when creating lists of elements. Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside an array to give the elements a stable identity.
+
+## [Refs](https://facebook.github.io/react/docs/refs-and-the-dom.html)
+React supports a special attribute that you can attach to any component. The `ref` attribute can be a string or a callback function. When the `ref` attribute is a callback function, the function receives the underlying DOM element as its argument. This allows you to have direct access to the DOM element.


String refs are legacy and are likely to be removed in the future. I guess it's okay for us to mention them here though. 😄

the function receives the underlying DOM element as its argument

Maybe we should say "DOM element or component instance"?

bvaughn · 2017-10-16T06:03:41Z

content/docs/reference-glossary.md

+## [Events](https://facebook.github.io/react/docs/handling-events.html) 
+Handling events with React elements has some syntactic differences:
+
+* React events are named using camelCase, rather than lowercase.


nit: "React event handlers"

mrscobbler · 2017-10-17T16:52:13Z

I just updated the content to reflect the changes suggested above -- it looks like the tests failed? I clicked on the details and I couldn't find any information on what was wrong.

bvaughn · 2017-10-17T17:32:09Z

CI is failing across the board at the moment, not just this PR. 😄

I can't even get the failing CI builds to load. They either crash my browser (Chrome) or hang forever with a circular spinner (Firefox and Safari).

bvaughn · 2017-10-17T17:36:27Z

I ran yarn ci-check on your branch locally and there are no errors, so we can just ignore the CI failure for now.

bvaughn

This looks great!

I left 2 small suggestions for consideration. Let me know your thoughts and I'm happy to merge this.

Thanks a bunch!

bvaughn · 2017-10-17T17:39:58Z

content/docs/reference-glossary.md

+
+
+## ES6/ES2015/ES7/ES2016/ES8/ES2017
+ These acronyms all refer to the most recent versions of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, `let` and `const` statements. ES8/ES2017 was finalized in June 2017 and includes async/await functionality. 


What do you think about linking externally for details? Maybe something like...

ES6/ES2015, ES7/ES2016, ES8/ES2017

These acronyms all refer to recent versions of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. They include many additions to the previous versions such as: arrow functions, classes, template literals, let and const statements. You can learn more about specific versions here.

Great -- will add

bvaughn · 2017-10-17T17:42:14Z

content/docs/reference-glossary.md

+ A "key" is a special string attribute you need to include when creating arrays of elements. Keys help React identify which items have changed, are added, or are removed. Keys should be given to the elements inside an array to give the elements a stable identity.
+
+## [Refs](/docs/refs-and-the-dom.html)
+React supports a special attribute that you can attach to any component. The `ref` attribute can be a string or a callback function. When the `ref` attribute is a callback function, the function receives the underlying DOM element as its argument. This allows you to have direct access to the DOM element or component instance.


I still think we should tweak this wording slightly:

the function receives the underlying DOM element or class instance (depending on the type of element) as its argument

mrscobbler · 2017-10-17T18:52:17Z

Just made the two changes! Thanks! 😄

bvaughn

Thanks 😄

…actjs#153) feat: Complete the translation of the `error-boundaries.md`. reactjs/zh-hans.react.dev@3ad3ca2

adding glossary content

37feb36

facebook-github-bot added the CLA Signed label Oct 12, 2017

mrscobbler mentioned this pull request Oct 12, 2017

New guides wanted #83

Closed

10 tasks

alexkrolick reviewed Oct 13, 2017

View reviewed changes

bvaughn reviewed Oct 16, 2017

View reviewed changes

updating text based on feedback from pull request

2fce3fa

bvaughn reviewed Oct 17, 2017

View reviewed changes

a few more changes

8e9703d

bvaughn approved these changes Oct 17, 2017

View reviewed changes

bvaughn merged commit 7267a39 into reactjs:master Oct 17, 2017

BetterZxx pushed a commit to BetterZxx/react.dev that referenced this pull request Mar 21, 2023

docs(cn): translate content/docs/error-boundaries.md into Chinese (re…

b65c10e

…actjs#153) feat: Complete the translation of the `error-boundaries.md`. reactjs/zh-hans.react.dev@3ad3ca2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Porting over glossary content from old repository #153

Porting over glossary content from old repository #153

mrscobbler commented Oct 12, 2017

reactjs-bot commented Oct 12, 2017 •

edited

Loading

alexkrolick Oct 13, 2017

mrscobbler Oct 13, 2017

bvaughn left a comment

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler Oct 16, 2017

bvaughn Oct 16, 2017

bvaughn Oct 16, 2017

bvaughn Oct 16, 2017

mrscobbler commented Oct 17, 2017

bvaughn commented Oct 17, 2017 •

edited

Loading

bvaughn commented Oct 17, 2017

bvaughn left a comment

bvaughn Oct 17, 2017

mrscobbler Oct 17, 2017

bvaughn Oct 17, 2017

mrscobbler commented Oct 17, 2017

bvaughn left a comment



		## ES6/ES2015
		ES6 AKA ES2015 is the current version of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, and `let` and `const` statements.



		## ES6/ES2015/ES7/ES2016/ES8/ES2017
		These acronyms all refer to the most recent versions of the ECMAScript Language Specification standard, which the JavaScript language is an implementation of. It includes many additions to the previous versions such as: arrow functions, classes, template literals, `let` and `const` statements. ES8/ES2017 was finalized in June 2017 and includes async/await functionality.

Porting over glossary content from old repository #153

Porting over glossary content from old repository #153

Conversation

mrscobbler commented Oct 12, 2017

reactjs-bot commented Oct 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mrscobbler commented Oct 17, 2017

bvaughn commented Oct 17, 2017 • edited Loading

bvaughn commented Oct 17, 2017

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ES6/ES2015, ES7/ES2016, ES8/ES2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mrscobbler commented Oct 17, 2017

bvaughn left a comment

Choose a reason for hiding this comment

reactjs-bot commented Oct 12, 2017 •

edited

Loading

bvaughn commented Oct 17, 2017 •

edited

Loading