Cleanup stray markdown files, update contributing guidelines

Summary: Several changes here. The `Text.md` and `PixelRatio.md` files were appended to the autodocs during site generation. This seemed excessive for just two files, so I've just merged the content into the autodocs themselves. It should help us simplify the website generation process in the future. I've also merged IssueGuidelines.md and PullRequestGuidelines.md into the Contribution/Maintainers guidelines to improve their visibility. Finally, I renamed Help to Community in the nav bar. Ran the website locally, and verified every page rendered as expected: the Community page, Contributing page, Maintainers page. Closes facebook#15374 Differential Revision: D5567400 Pulled By: hramos fbshipit-source-id: e06056edb12c9a17319fe1af46b2ef3a2e1b5854
sebadima · Aug 4, 2017 · 5be8c4a · 5be8c4a
1 parent 259eac8
commit 5be8c4a
Show file tree

Hide file tree

Showing 15 changed files with 348 additions and 303 deletions.
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -16,22 +16,16 @@
   If you answered "No":
 
     We use GitHub Issues exclusively for tracking bugs in React Native. If you're looking for help,
-    check out the How to Get In Touch section of the following guide:
-    https://facebook.github.io/react-native/docs/contributing.html#how-to-get-in-touch
+    the Community page at http://facebook.github.io/react-native/support.html list various resources 
+    that should help you get started.
 
   Now scroll below!
 -->
 
-
-### Have you read the Bugs section of the How to Contribute guide?
+### Have you read the [Contributing Guidelines](https://facebook.github.io/react-native/docs/contributing.html)?
 
 (Write your answer here.)
 
-<!--
-  Please read through the bug reporting guidelines thoroughly:
-  https://facebook.github.io/react-native/docs/contributing.html#bugs
--->
-
 ### Environment
 
 <!--

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,9 +1,16 @@
 <!--
-Thank you for sending the PR!
+Thank you for sending the PR! We appreciate you spending the time to work on these changes. 
 
-If you changed any code, please provide us with clear instructions on how you verified your changes work. In other words, a test plan is *required*. Bonus points for screenshots and videos!
+Help us understand your motivation by explaining why you decided to make this change.
 
-Please read the Contribution Guidelines at https://github.com/facebook/react-native/blob/master/CONTRIBUTING.md to learn more about contributing to React Native.
+You can learn more about contributing to React Native here: http://facebook.github.io/react-native/docs/contributing.html
 
 Happy contributing!
+
 -->
+
+(Write your motivation here.)
+
+## Test Plan
+
+(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,25 +3,25 @@
 <!-- generated_contributing_start -->
 React Native is one of Facebook's first open source projects that is both under very active development and is also being used to ship code to everybody using Facebook's mobile apps. If you're interested in contributing to React Native, hopefully this document makes the process for contributing clear.
 
-Core contributors to React Native meet monthly and post their meeting notes on the [React Native blog](https://facebook.github.io/react-native/blog). You can also find ad hoc discussions in the [React Native Core Contributors](https://www.facebook.com/groups/reactnativeoss/) Facebook group.
-
 ## [Code of Conduct](https://code.facebook.com/codeofconduct)
 
 Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
 
-## How to contribute
+## Get involved
 
 There are many ways to contribute to React Native, and many of them do not involve writing any code. Here's a few ideas to get started:
 
 * Simply start using React Native. Go through the [Getting Started](http://facebook.github.io/react-native/docs/getting-started.html) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](http://facebook.github.io/react-native/docs/contributing.html#reporting-new-issues).
 * Look through the [open issues](https://github.com/facebook/react-native/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](http://facebook.github.io/react-native/docs/contributing.html#triaging-issues-and-pull-requests).
-* If you find an issue you would like to fix, [open a pull request](http://facebook.github.io/react-native/docs/contributing.html#your-first-pull-request). Issues tagged as [`Good First Task`](https://github.com/facebook/react-native/labels/Good%20First%20Task) are a good place to get started.
+* If you find an issue you would like to fix, [open a pull request](http://facebook.github.io/react-native/docs/contributing.html#your-first-pull-request). Issues tagged as [_Good First Task_](https://github.com/facebook/react-native/labels/Good%20First%20Task) are a good place to get started.
 * Read through the [React Native docs](http://facebook.github.io/react-native/docs). If you find anything that is confusing or can be improved, you can make edits by clicking "Improve this page" at the bottom of most docs.
 * Browse [Stack Overflow](https://stackoverflow.com/questions/tagged/react-native) and answer questions. This will help you get familiarized with common pitfalls or misunderstandings, which can be useful when contributing updates to the documentation.
 * Take a look at the [features requested](https://react-native.canny.io/feature-requests) by others in the community and consider opening a pull request if you see something you want to work on.
 
 Contributions are very welcome. If you think you need help planning your contribution, please hop into [#react-native](https://discord.gg/0ZcbPKXt5bZjGY5n) and let people know you're looking for a mentor.
 
+Core contributors to React Native meet monthly and post their meeting notes on the [React Native blog](https://facebook.github.io/react-native/blog). You can also find ad hoc discussions in the [React Native Core Contributors](https://www.facebook.com/groups/reactnativeoss/) Facebook group.
+
 ### Triaging issues and pull requests
 
 One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in.
@@ -31,10 +31,7 @@ One great way you can contribute to the project without writing any code is to h
 * Flag issues that are stale or that should be closed.
 * Ask for test plans and review code.
 
-Adding labels, closing and reopening issues, and merging pull requests is, as you may expect, limited to a subset of contributors. Simply commenting on the issue or pull request can still go a long way towards helping us keep the number of outstanding issues under control.
-
-Once you have become an active contributor in the community, you may gain access to the Facebook GitHub Bot, allowing you to perform some of these operations yourself. You can learn more about the bot in the [maintainer's guide](docs/maintainers.html#facebook-github-bot).
-
+You can learn more about handling issues in the [maintainer's guide](docs/maintainers.html#handling-issues).
 
 ## Our development process
 
@@ -52,7 +49,7 @@ To see what changes are coming and provide better feedback to React Native contr
 
 We use [GitHub Issues](https://github.com/facebook/react-native/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you a are certain this is a new, unreported bug, you can submit a [bug report](http://facebook.github.io/react-native/docs/contributing.html#reporting-new-issues).
 
-If you have questions about using React Native, the [help page](http://facebook.github.io/react-native/support.html) list various resources that should help you get started.
+If you have questions about using React Native, the [Community page](http://facebook.github.io/react-native/support.html) list various resources that should help you get started.
 
 We also have a [place where you can request features or enhancements](https://react-native.canny.io/feature-requests). If you see anything you'd like to be implemented, vote it up and explain your use case.
 
@@ -87,7 +84,7 @@ We have a list of [beginner friendly issues](https://github.com/facebook/react-n
 
 If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, we have a [place to track feature requests](https://react-native.canny.io/feature-requests).
 
-If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend [filing an issue](https://github.com/facebook/react-native/issues/new). This lets us reach an agreement on your proposal before you put significant effort into it.
+If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend [filing an issue](https://github.com/facebook/react-native/issues/new?title=%5BProposal%5D) that includes `[Proposal]` in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare. If you have been contributing to the project long enough, you will probably already have access to the [React Native Core Contributors](https://www.facebook.com/groups/reactnativeoss/) Facebook Group, where this sort of discussion is usually held.
 
 If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
 
@@ -100,7 +97,7 @@ Small pull requests are much easier to review and more likely to get merged. Mak
 1. Fork [the repository](https://github.com/facebook/react-native) and create your branch from `master`.
 2. Add the copyright notice to the top of any new files you've added.
 3. Describe your [**test plan**](https://facebook.github.io/react-native/docs/contributing.html#test-plan) in your commit.
-4. Ensure [**tests pass**](https://facebook.github.io/react-native/docs/contributing.html#continuous-integration-tests) on both Travis and Circle CI.
+4. Ensure [**tests pass**](https://facebook.github.io/react-native/docs/contributing.html#contrinuous-integration-tests) on both Travis and Circle CI.
 5. Make sure your code lints (`npm run lint`).
 6. If you haven't already, [sign the CLA](https://code.facebook.com/cla).
 

diff --git a/Libraries/Text/Text.js b/Libraries/Text/Text.js
@@ -50,9 +50,10 @@ const viewConfig = {
  *
  * `Text` supports nesting, styling, and touch handling.
  *
- * In the following example, the nested title and body text will inherit the `fontFamily` from
- *`styles.baseText`, but the title provides its own additional styles.  The title and body will
- * stack on top of each other on account of the literal newlines:
+ * In the following example, the nested title and body text will inherit the
+ * `fontFamily` from `styles.baseText`, but the title provides its own 
+ * additional styles.  The title and body willstack on top of each other on 
+ * account of the literal newlines:
  *
  * ```ReactNativeWebPlayer
  * import React, { Component } from 'react';
@@ -94,6 +95,194 @@ const viewConfig = {
  * // skip this line if using Create React Native App
  * AppRegistry.registerComponent('TextInANest', () => TextInANest);
  * ```
+ * 
+ * ## Nested text
+ * 
+ * Both iOS and Android allow you to display formatted text by annotating 
+ * ranges of a string with specific formatting like bold or colored text 
+ * (`NSAttributedString` on iOS, `SpannableString` on Android). In practice, 
+ * this is very tedious. For React Native, we decided to use web paradigm for 
+ * this where you can nest text to achieve the same effect.
+ * 
+ * 
+ * ```ReactNativeWebPlayer
+ * import React, { Component } from 'react';
+ * import { AppRegistry, Text } from 'react-native';
+ *
+ * export default class BoldAndBeautiful extends Component {
+ *   render() {
+ *     return (
+ *       <Text style={{fontWeight: 'bold'}}>
+ *         I am bold
+ *         <Text style={{color: 'red'}}>
+ *           and red
+ *         </Text>
+ *       </Text>
+ *     );
+ *   }
+ * }
+ * 
+ * // skip this line if using Create React Native App
+ * AppRegistry.registerComponent('AwesomeProject', () => BoldAndBeautiful);
+ * ```
+ * 
+ * Behind the scenes, React Native converts this to a flat `NSAttributedString` 
+ * or `SpannableString` that contains the following information:
+ * 
+ * ```javascript
+ * "I am bold and red"
+ * 0-9: bold
+ * 9-17: bold, red
+ * ```
+ * 
+ * ## Nested views (iOS only)
+ * 
+ * On iOS, you can nest views within your Text component. Here's an example:
+ * 
+ * ```ReactNativeWebPlayer
+ * import React, { Component } from 'react';
+ * import { AppRegistry, Text, View } from 'react-native';
+ * 
+ * export default class BlueIsCool extends Component {
+ *   render() {
+ *     return (
+ *       <Text>
+ *         There is a blue square
+ *         <View style={{width: 50, height: 50, backgroundColor: 'steelblue'}} />
+ *         in between my text.
+ *       </Text>
+ *     );
+ *   }
+ * }
+ * 
+ * // skip this line if using Create React Native App
+ * AppRegistry.registerComponent('AwesomeProject', () => BlueIsCool);
+ * ```
+ * 
+ * > In order to use this feature, you must give the view a `width` and a `height`.
+ * 
+ * ## Containers
+ * 
+ * The `<Text>` element is special relative to layout: everything inside is no 
+ * longer using the flexbox layout but using text layout. This means that 
+ * elements inside of a `<Text>` are no longer rectangles, but wrap when they 
+ * see the end of the line.
+ * 
+ * ```javascript
+ * <Text>
+ *   <Text>First part and </Text>
+ *   <Text>second part</Text>
+ * </Text>
+ * // Text container: all the text flows as if it was one
+ * // |First part |
+ * // |and second |
+ * // |part       |
+ * 
+ * <View>
+ *   <Text>First part and </Text>
+ *   <Text>second part</Text>
+ * </View>
+ * // View container: each text is its own block
+ * // |First part |
+ * // |and        |
+ * // |second part|
+ * ```
+ *
+ * ## Limited Style Inheritance
+ * 
+ * On the web, the usual way to set a font family and size for the entire 
+ * document is to take advantage of inherited CSS properties like so:
+ * 
+ * ```css
+ * html {
+ *   font-family: 'lucida grande', tahoma, verdana, arial, sans-serif;
+ *   font-size: 11px;
+ *   color: #141823;
+ * }
+ * ```
+ *
+ * All elements in the document will inherit this font unless they or one of 
+ * their parents specifies a new rule.
+ * 
+ * In React Native, we are more strict about it: **you must wrap all the text 
+ * nodes inside of a `<Text>` component**. You cannot have a text node directly
+ * under a `<View>`.
+ *
+ * 
+ * ```javascript
+ * // BAD: will raise exception, can't have a text node as child of a <View>
+ * <View>
+ *   Some text
+ * </View>
+ * 
+ * // GOOD
+ * <View>
+ *   <Text>
+ *     Some text
+ *   </Text>
+ * </View>
+ * ```
+ * 
+ * You also lose the ability to set up a default font for an entire subtree. 
+ * The recommended way to use consistent fonts and sizes across your 
+ * application is to create a component `MyAppText` that includes them and use 
+ * this component across your app. You can also use this component to make more 
+ * specific components like `MyAppHeaderText` for other kinds of text.
+ * 
+ * ```javascript
+ * <View>
+ *   <MyAppText>Text styled with the default font for the entire application</MyAppText>
+ *   <MyAppHeaderText>Text styled as a header</MyAppHeaderText>
+ * </View>
+ * ```
+ * 
+ * Assuming that `MyAppText` is a component that simply renders out its 
+ * children into a `Text` component with styling, then `MyAppHeaderText` can be 
+ * defined as follows:
+ * 
+ * ```javascript
+ * class MyAppHeaderText extends Component {
+ *   render() {
+ *     <MyAppText>
+ *       <Text style={{fontSize: 20}}>
+ *         {this.props.children}
+ *       </Text>
+ *     </MyAppText>
+ *   }
+ * }
+ * ```
+ * 
+ * Composing `MyAppText` in this way ensures that we get the styles from a 
+ * top-level component, but leaves us the ability to add / override them in 
+ * specific use cases.
+ * 
+ * React Native still has the concept of style inheritance, but limited to text 
+ * subtrees. In this case, the second part will be both bold and red.
+ * 
+ * ```javascript
+ * <Text style={{fontWeight: 'bold'}}>
+ *   I am bold
+ *   <Text style={{color: 'red'}}>
+ *     and red
+ *   </Text>
+ * </Text>
+ * ```
+ * 
+ * We believe that this more constrained way to style text will yield better
+ * apps:
+ * 
+ * - (Developer) React components are designed with strong isolation in mind: 
+ * You should be able to drop a component anywhere in your application, 
+ * trusting that as long as the props are the same, it will look and behave the 
+ * same way. Text properties that could inherit from outside of the props would 
+ * break this isolation.
+ * 
+ * - (Implementor) The implementation of React Native is also simplified. We do 
+ * not need to have a `fontFamily` field on every single element, and we do not 
+ * need to potentially traverse the tree up to the root every time we display a 
+ * text node. The style inheritance is only encoded inside of the native Text 
+ * component and doesn't leak to other components or the system itself.
+ * 
  */
 
 // $FlowFixMe(>=0.41.0)

diff --git a/Libraries/Utilities/PixelRatio.js b/Libraries/Utilities/PixelRatio.js
@@ -16,7 +16,7 @@ var Dimensions = require('Dimensions');
 /**
  * PixelRatio class gives access to the device pixel density.
  *
- * ### Fetching a correctly sized image
+ * ## Fetching a correctly sized image
  *
  * You should get a higher resolution image if you are on a high pixel density
  * device. A good rule of thumb is to multiply the size of the image you display
@@ -29,6 +29,33 @@ var Dimensions = require('Dimensions');
  * });
  * <Image source={image} style={{width: 200, height: 100}} />
  * ```
+ * 
+ * ## Pixel grid snapping
+ * 
+ * In iOS, you can specify positions and dimensions for elements with arbitrary 
+ * precision, for example 29.674825. But, ultimately the physical display only
+ * have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334
+ * for iPhone 6. iOS tries to be as faithful as possible to the user value by 
+ * spreading one original pixel into multiple ones to trick the eye. The 
+ * downside of this technique is that it makes the resulting element look 
+ * blurry.
+ * 
+ * In practice, we found out that developers do not want this feature and they 
+ * have to work around it by doing manual rounding in order to avoid having 
+ * blurry elements. In React Native, we are rounding all the pixels 
+ * automatically.
+ * 
+ * We have to be careful when to do this rounding. You never want to work with 
+ * rounded and unrounded values at the same time as you're going to accumulate 
+ * rounding errors. Having even one rounding error is deadly because a one 
+ * pixel border may vanish or be twice as big.
+ * 
+ * In React Native, everything in JavaScript and within the layout engine works
+ * with arbitrary precision numbers. It's only when we set the position and 
+ * dimensions of the native element on the main thread that we round. Also, 
+ * rounding is done relative to the root rather than the parent, again to avoid 
+ * accumulating rounding errors.
+ * 
  */
 class PixelRatio {
   /**