rachelnabors commented 4 years ago

🍾🎉🎈Thank you everyone! We are mission complete!🍾🎉🎈

We have a lot of component and API docs that need updating! The good news is that updating these docs can be a fun way to become more familiar with React Native’s core code while contributing to docs that help thousands of learners around the world! If this looks intimidating, we have you covered! There’s a handy guide below that should help you out :)

What needs updating?

Update the API to reflect the props and methods reflected in core
Ensure example code is 1) in a Snack player and 2) uses function components and Hooks:
- Add example code if it is missing
- Update example code to use function components and React Hooks
- Put example code in an embedded Snack player

How to contribute?

First, select a component or API from the table below.
Choose a single update to make:
1. Update the API
2. Add missing example code
3. Convert existing example code to use function components and React Hooks
4. Embed any existing example code in a Snack player
Comment below on what component/API you want to take on and which fix; I'll update the matrix with your name
Submit your PR tagged with this issue

When your PR is merged, we’ll convert your name into a checkmark, indicating completion!

Update the API to reflect the props and methods reflected in core

This part requires a little investigating! Check react-native/Libraries/YourComponent and react-native/Libraries/Components/YourComponent for your component or API’s list of props. Sometimes they can be hidden, like the LayoutProps API is in react-native/Libraries/StyleSheet/StyleSheetTypes.js.

Pro tip: If you get stuck, search for “YourComponent.js” or search the “YourComponent” with a prop or method already listed.

Add missing example code

If there is no example code, add a new example using function components and Hooks. Embed your code with a Snack player like so:

```SnackPlayer name=Component/API%20Example

// Example code goes here


### Convert existing example code to use function components and Hooks

If there’s a class component example already, use this [handy guide on converting class components to function components and Hooks](https://scotch.io/bar-talk/convert-class-components-to-functional-components-in-a-react-project-solution-to-code-challenge-14) to make a function component example. Then use the following code snippet to keep both function and class component examples (please remove the first and final ` ``` `—markdown formating trouble!):

<div class="toggler">
  <ul role="tablist" class="toggle-syntax">
    <li id="functional" class="button-functional" aria-selected="false" role="tab" tabindex="0" aria-controls="functionaltab" onclick="displayTabs('syntax', 'functional')">
      Function Component Example
    </li>
    <li id="classical" class="button-classical" aria-selected="false" role="tab" tabindex="0" aria-controls="classicaltab" onclick="displayTabs('syntax', 'classical')">
      Class Component Example
    </li>
  </ul>
</div>

<block class="functional syntax" />

```SnackPlayer name=Component/API%20Function%20Component%20Example

// Function Component Example goes here


// Class Example goes here

If there isn’t a class component example or there was already a function component example, just use the following code to embed just a function component example.

Embed any example code with a Snack player

```SnackPlayer name=Component/API%20Example

// Example code goes here



### Submit your PR!

Follow the repo's setup instructions [here](https://github.com/facebook/react-native-website). 

> **Remember** your doc changes will be under facebook.github.io/react-native/docs/**next/**yourcomponent, _not_ facebook.github.io/react-native/docs/yourcomponent

1. Work on master docs (docs/*.md), **not versioned ones** (website/versioned_docs/version-0.*/*.md)
2. Tag your PR with this issue #1579 so it gets properly recognized

### Code Tips

* Extract styles to `StyleSheet` outside of component and at bottom of sample
* Use arrow functions instead of anonymous functions
* Do not leave unused `import`s 
* Sort `import`s alphabetically
* Remember to use semicolons (especially after `export`s)
* Name your Snack "<Component/API>%20Example"
* If the API or component is platform specific, specify which platforms for the Snack player to show like so: ` ```SnackPlayer name=AndroidOnlyAPI&supportedPlatforms=web,android`
* If the API or component has platform specific parts, use `supportedPlatforms` 

Before committing...

* Run `yarn prettier` to ensure your code is made pretty before committing.
* Also `cd website` and `yarn start` to generate any changes to sidebars

## Docs Drive Leaderboard

**🍾🎉🎈Thank you to all these wonderful folks!🍾🎉🎈**

These are the people and their contributions to the docs!

* @ronnyiscoding = { ActivityIndicator : #1590, ImageStyleProps : #1602 }
* @dsznajder = { Button : #1592, TouchableHighlight : #1591 }
* @lfoliveir4 = { FlatList : null}
* @amandeepmittal = { Image : #1582, View : #1582, Share : #1674 }
* @nnajiabraham = { KeyboardAvoidingView : null, VirtualizedList : [#1742, #1632], AppRegistry : #1740 }
* @Darking360 = { Modal : #1605 }
* @kaioduarte = { Picker : #1595, Switch : #1594, TouchableOpacity : #1596, ShadowProps: #1664, Text Style Props : #1710 }
* @espipj = { StatusBar : #1624, TouchableNativeFeedback : #1646, ToastAndroid : #1614, DrawerLayoutAndroid : #1683, Layout Props : #1750 }
* @DaniAkash = { Alert : #1597, Dimensions : #1671, Animated : #1691, LayoutAnimation : #1721, BackHandler : #1685, Transforms : #1613, PanResponder : #1691 }
* @mitulsavani = { View Style Props : #1612 }
* @mdabrowka = { AccessibilityInfo : #1629 }
* @lcelso = { StyleSheet : #1626 }
* @alvessteve = { ImageBackground : #1598 }
* @tsawan = { Text : #1623, AppState : #1666 }
* @Naturalclar = { TextInput : #1584 } 
* @simek = { ActionSheetIOS : #1680, PixelRatio : #1687, Easing : #1682, Settings : #1700 }
* @mohamedsgap = { AppState : #1695, Vibration : #1707, Systrace : #1749 }
* @kakukakug = { TouchableWithoutFeedback : #1686 }
* @ahmdtalat = { Keyboard : #1619 }
* @gedeagas = { Animated : #1702, Flatlist : [#1705, #1729], PermissionsAndroid : #1720, SectionList : [#1754, #1717] }
* @danilobrinu = { InteractionManager : #1712, Linking : #1751 }

DaniAkash commented 4 years ago

@rachelnabors Summary of my PRs LayoutAnimation - https://github.com/facebook/react-native-website/pull/1609 [WIP] Clipboard - https://github.com/facebook/react-native-website/pull/1599 [WIP] DatePickerIOS - https://github.com/facebook/react-native-website/pull/1583 Dimensions - https://github.com/facebook/react-native-website/pull/1601 Alert - https://github.com/facebook/react-native-website/pull/1597

It'd be helpful if you can add these to the Components and APIs update progress. Also, I'll be picking up Animated library next @jeremy-deutsch look forward to my PR soon 👍

miganga commented 4 years ago

@rachelnabors I would like to take on Layout Props api to update. Thank you.

rachelnabors commented 4 years ago

@lfoliveir4 :

As I understand it, is it necessary to make an example with hooks and classes referring to the API?

You only need to make examples with function components and Hooks. If there is ALREADY an example with class components, then use the toggler code to show both examples together :) You should only make new examples with function components/hooks

rachelnabors commented 4 years ago

Folks, I have updated the matrix to reflect the projects you've claimed! Phew! Time to review some of your pull requests! Thanks so much for contributing, and if you haven't contributed yet, just claim a component here!

lcelso commented 4 years ago

I'll take the Linking and StyleSheet

Simek commented 4 years ago

I was reviewing today a few PRs related to this issue and I would like to summarize some tips according to code quality and best practices of those new examples.

There are minor things but overall this code could be used by many developers and mistakes or negligence here could be replicated further. There is no bad intent I just assume that we all want to have the best examples here 😉

Please pay a bit attention for those details if possible:

work on master docs (docs/*.md) not versioned ones (website/versioned_docs/version-0.*/*.md)
extract styles to StyleSheet outside of component if necessary
use arrow function instead of function keyword
do not leave unused imports and sort imports alphabetically
remember about semicolons (especially after exports)
use same quotation marks across whole example (I don't know which are prefered here " or ' but be consistent)
remember about specifying supportedPlatforms for the Snack if component requires that (example: c7c7929dfa0c20af5bf953c45708ce21ca0019f8)
brake lines even more often than in your IDE - Snack code block fits only 66 characters per line
do not overcomplicate Snack names

That's all from me. Thank you all for your contributions. Keep up the good work!

lcelso commented 4 years ago

@Simek

I agree with you, however I have some points in which I wanted us to reflect.

We are using SnackPlayer to generate the example together with the Expo.

Positive points:

Code editor Demo for three versions, web / ios and android

Negative points:

Project structure using the docusaurus, leaves devs a little limited, since these are markdown files, the examples in react within it are without the sixtaxe highlight.

Perhaps there is some configuration in which we can make the prettier to solve this. In js and html files I already made certain settings for this. However, we got to the point of using markdown syntax together with React (SnackPlayer).

What I thought, was maybe to rethink the architecture of the project maybe using gatsbyjs, in which we have integrations with github pages, among other points.

Searching here I saw that this subject was addressed in another post as well and that this is not currently in our plans. But I think the debate is also worth it, right?

Ps. sorry for my terrible english

mdabrowka commented 4 years ago

I will work on refactoring AccessibilityInfo example into a function component with Hooks

Simek commented 4 years ago

@lcelso I agree that developing examples could be a bit more difficult due to fact that code is embedded in Markdown. Having examples in separate JS files would be nice (for example we can setup linter than etc.) but changing project architecture and converting all docs could be a challenging and daunting process. I don't even know if it's possible within Docusaurus. Also switch to Gatsby is not likely since Docusaurus is a Facebook product and Gatsby is not (also purpose of those platforms is bit different). Many code editors/IDEs this days can highlight JS code properly inside other type files (screenshot). Running website on localhost and developing with live preview also helps a lot.

But back to main topic. @rachelnabors Since Clipboard API is being deprecated (#1608) I would like to propose removal of this API from the TODO list (I would like to apologize authors of #1599 and #1604 for that).

It's also a good opportunity to start conversation about removing ALL existing examples from the deprecated components (leaving short description and reference only) before next major release. This whole idea started here https://github.com/facebook/react-native-website/pull/1583#issuecomment-583345444 but I think that this thread is a better place for this conversation.

Few pages in the master docs right now follow this pattern (ImageEditor, PickerIOS, Slider) but most of deprecated pages include examples. In my opinion removing those examples can force (mainy new) users to follow deprecation notice and use the proper maintained and up to date package which always contains an example or a few of them in the README. There are more benefits to users regarding to compatibility, or better support with issues for those packages but I would like also to hear you opinion about this idea.

espipj commented 4 years ago

Hey @rachelnabors ! I'll be making some changes in the TextInput API docs 😄

I'll be picking up ToastAndroid as well... 🍞

DaniAkash commented 4 years ago

While testing out the Animated API, I had to write some transforms and realized I might as well use them as an example for the Transforms API. However, as per https://github.com/facebook/react-native/issues/27649, the skew transform isn't working on Android.

Skew on iOS:

Skew on Android:

Help from expert Android Developers are appreciated at facebook/react-native#27649

ahmdtalat commented 4 years ago

Hello guys, I've an issue and need you help. when I make a change to the docs. it does not render although I'm using the latest version as the documentation says Changes to /docs will only be visible in the latest version of the documentation (master). . to solve this. I have to run yarn run version 0.62. but is that's ok? I mean what if I want to push changes. should I push the docs changes only?

DaniAkash commented 4 years ago

@ahmdtalat the changes are in the master documentation.

To open master documentation: you can directly click on the version number next to the "React Native" title icon of the page and see the list of all versions including the master documentation. You can view your changes in this section. No need to run version 0.62 command

Hope this answers your question...

rachelnabors commented 4 years ago

I've updated the matrix with new contributors and some new protips to help folks contributing their code (thanks, @Simek!) Please check them out under "Submit your PR!" and "Code Tips"! Thanks again to everyone for contributing!

lfoliveir4 commented 4 years ago

@lfoliveir4 :

As I understand it, is it necessary to make an example with hooks and classes referring to the API?

You only need to make examples with function components and Hooks. If there is ALREADY an example with class components, then use the toggler code to show both examples together :) You should only make new examples with function components/hooks

How do I stop checking the lib that I'm going to do the example?

lfoliveir4 commented 4 years ago

@lfoliveir4 :

As I understand it, is it necessary to make an example with hooks and classes referring to the API?

You only need to make examples with function components and Hooks. If there is ALREADY an example with class components, then use the toggler code to show both examples together :) You should only make new examples with function components/hooks

How do I stop checking the lib that I'm going to do the example?

@rachelnabors I will make the contribution with the FlatList component Its link to PR : https://github.com/facebook/react-native-website/pull/1620

DaniAkash commented 4 years ago

I've updated the matrix with new contributors and some new protips to help folks contributing their code (thanks, @Simek!) Please check them out under "Submit your PR!" and "Code Tips"! Thanks again to everyone for contributing!

@rachelnabors add me to the Transforms API, I have already raised a PR https://github.com/facebook/react-native-website/pull/1613

ahmdtalat commented 4 years ago

Hello Guys, I added Keyboard API example using function components & hooks PR #1619

mohamedsgap commented 4 years ago

Can't find TabBarIOS in react-native/Libraries to start updating its API @rachelnabors

lcelso commented 4 years ago

@Simek @rachelnabors I understand your point of view and agree that we should have a scenario in which editing the javascript files is a little easier.

I was analyzing some PRs here and I miss some patterns, like 2 spaces, single quotes, among other points, in which I believe we can define this here as a team, what do you think?

Another point is, I am Brazilian and here we have only 5% of the people who speak the English language link. Reflecting on this, do you think we can have some language context? Mainly in the context for examples.

Another point that would be interesting for a better flow, would be some channel in Slack for better communication, what do you think?

On the points that you raised from the interruption, I really totally agree.

lcelso commented 4 years ago

Hi guys, can someone review this for me?

@Simek @rachelnabors

1626

tsawan commented 4 years ago

@rachelnabors I can also change "Image" and "AppState" examples to use functional components and hooks.

luism3861 commented 4 years ago

@rachelnabors my 2 pr's #1627 #1617

DaniAkash commented 4 years ago

I'm struggling to get the RNTester app running in my machine. Anyone else facing issue with running RNTester?

rachelnabors commented 4 years ago

Hi everyone, sorry for the absence. Got sick again!

Matrix is updated!

rachelnabors commented 4 years ago

@lcelso We have a discord we could use to coordinate, but then we'd have to track in two locations, which historically can be even more confusing! If you want to team up with someone, I suggest you reach out to them personally and choose the format of your choice to coordinate :) Could you expand on "do you think we can have some language context? Mainly in the context for examples."?

mitulsavani commented 4 years ago

Hi @rachelnabors, I see that you recently updated the metrics and tick marked View Style Props and referenced #1614 on it. I am not sure if that was a typo if so then, my PR is #1612 FYI.

I wonder if there is anything else that I need to finish for View Style Props? If not then, I can start working on other pending work

lcelso commented 4 years ago

@rachelnabors Hello, I believe that a faster communication channel could speed up some points, such as clearing doubts, which we can remove / discontinue.

Especially between some points of decisions and this done we can make official here.

About languages, I was seeing react.org and this is already done there.

This is a point if we have a group on Slack or anywhere else that we will have a more fluid communication.

We can discuss tools or other things like that and I try to have a better agility to give things a better flow.

What do you say?

amandeepmittal commented 4 years ago

Hi @rachelnabors, I will update the Share API by adding functional and hooks example since it already has the class component example.

Simek commented 4 years ago

@rachelnabors Could you asses the idea proposed in https://github.com/facebook/react-native-website/issues/1579#issuecomment-583735028?

DaniAkash commented 4 years ago

@lcelso I agree that developing examples could be a bit more difficult due to fact that code is embedded in Markdown. Having examples in separate JS files would be nice (for example we can setup linter than etc.) but changing project architecture and converting all docs could be a challenging and daunting process. I don't even know if it's possible within Docusaurus. Also switch to Gatsby is not likely since Docusaurus is a Facebook product and Gatsby is not (also purpose of those platforms is bit different). Many code editors/IDEs this days can highlight JS code properly inside other type files (screenshot). Running website on localhost and developing with live preview also helps a lot.

But back to main topic. @rachelnabors Since Clipboard API is being deprecated (#1608) I would like to propose removal of this API from the TODO list (I would like to apologize authors of #1599 and #1604 for that).

It's also a good opportunity to start conversation about removing ALL existing examples from the deprecated components (leaving short description and reference only) before next major release. This whole idea started here #1583 (comment) but I think that this thread is a better place for this conversation.

Few pages in the master docs right now follow this pattern (ImageEditor, PickerIOS, Slider) but most of deprecated pages include examples. In my opinion removing those examples can force (mainy new) users to follow deprecation notice and use the proper maintained and up to date package which always contains an example or a few of them in the README. There are more benefits to users regarding to compatibility, or better support with issues for those packages but I would like also to hear you opinion about this idea.

While it is a good idea to remove the options from the sidebar, I still feel removing the examples would be bit harsh for people who are already heavily using these components...

rachelnabors commented 4 years ago

@simek I can confirm that deprecated components will be removed from the sidebar but their legacy pages will live on quietly—there is no harm in finishing up the examples! I hope this settles things.

@amandeepmittal you're on Share, thanks!

@lcelso Will need to hear more support from other people for your idea—worry another communication channel now would slow down and split communications rather than keeping us moving in one direction with one source of truth—this location. Feel free to coordinate privately on individual collaborations, naturally.

@mitulsavani I'll correct the issue post haste.

Next up: I'll be removing pieces of the matrix that have been completed to make it easier to see what's left to do. Thanks, everyone, for your hard work so far!

Simek commented 4 years ago

@rachelnabors Are there any changes planned for the Components and APIs page? Would you like to mark in some way or even remove deprecated pages listed in there?

rachelnabors commented 4 years ago

@Simek Smart thinking! And to think I've been looking at this page the whole week without realizing it! What a cold! Good thing you're on the ball!

We should remove the deprecated components and APIs from the page as we are removing them from the sidebar as well. Would you like to handle that one?

lcelso commented 4 years ago

@rachelnabors @Simek

I created a channel for quick communication and central points of doubts here.

link to slack

However I agree that here we must have the data and everything that was talked about there registered here.

What do you say?

Because I think so, I am feeling our agility / decision making is very slow.

There are points of doubt about how we should do it and even points of discussion with better fluidity.

We currently have many PRs stopped a lot of them for many days. Among other points where we can try to start reviewing this.

Simek commented 4 years ago

@rachelnabors I think that "API" link in top bar which leads to ActivityIndicator page instead of Components and APIs page in next docs do not help either 😉

Back to the deprecation discussion - I would like to help with those changes but I'm still not 100% sure how to perform them.

In my opinion, in some point in time 0.61 docs should be regenerated to include all the work from this issue and more changes that landed on the next docs during last months (I assume this should happen before or on 0.62 release?).

Merging sidebar and Components and APIs deprecation cleanup PRs before refreshing 0.61 will cause a loss of some improvements (mainly deprecation indicators and notes because they are currently only on the next docs and are targeted to be deleted before/on 0.62 release). That is also the reason why I was talking about generating 0.62 docs when you asked about sidebar changes in earlier discussion.

Simek commented 4 years ago

@lcelso I think that Slack/Teams/Discord channel will help with communication and can streamline PR processes but you should remember that this is still a Facebook repo which is not officially maintained by the community.

In my opinion creating this kind of communication platform should be approved and managed by FB employees (maintainers). If your idea got a green light of course I will join along.

mitulsavani commented 4 years ago

@lcelso I think that Slack/Teams/Discord channel will help with communication and can streamline PR processes but you should remember that this is still a Facebook repo which is not officially maintained by the community.

In my opinion creating this kind of communication platform should be approved and managed by FB employees (maintainers). If your idea got a green light of course I will join along.

I definitely agree with @Simek opinion, @lcelso I recommend you to open an issue on core react native repo to discuss further about it.

lcelso commented 4 years ago

Hello guys,

I agree for this I opened the discussion here with @rachelnabors and she gave me this answer. If I got it wrong I'm sorry.

@lcelso Will need to hear more support from other people for your idea—worry another communication channel now would slow down and split communications rather than keeping us moving in one direction with one source of truth—this location. Feel free to coordinate privately on individual collaborations, naturally.

And if this suggestion is a bad point I would like to understand how we can resolve the points below:

Long standing PRs
Doubts of those who want to help and have a quick flow of responses
Discussions on topics that we can make obsolete or not
Define a development standardization (For example use 'or', etc.)

lcelso commented 4 years ago

@rachelnabors Acho que o link "API" na barra superior que leva à ActivityIndicatorpágina em vez da Components and APIspágina nos nextdocumentos também não ajuda😉

De volta à discussão sobre descontinuação - eu gostaria de ajudar com essas alterações, mas ainda não tenho 100% de certeza de como executá-las.

Na minha opinião, em algum momento os 0.61documentos devem ser regenerados para incluir todo o trabalho desse problema e mais alterações que chegaram aos nextdocumentos nos últimos meses (presumo que isso deva acontecer antes ou no 0.62lançamento?).

A mesclagem de Components and APIsPRs de limpeza da barra lateral e de descontinuação antes da atualização 0.61causará uma perda de algumas melhorias (principalmente indicadores e notas de descontinuação, porque eles estão atualmente apenas nos nextdocumentos e devem ser excluídos antes / no 0.62lançamento). Essa também é a razão pela qual eu estava falando sobre a geração de 0.62documentos quando você perguntou sobre alterações na barra lateral em discussões anteriores.

I would like to help with this too

jerocosio commented 4 years ago

Hi @rachelnabors I was looking at the missing components and I saw that TabBarIOS & TabBarIOS.item were deprecated on RN 0.5959 here's the CHANGELOG they don't appear on the docs for version 0.59 but they re appeared on version 60 and 61.

rachelnabors commented 4 years ago

@cosio55 Thank you for hunting that one down! I wish we could go back and remove it from all the following versions of the docs now. I'll remove it from the matrix. Much obliged!

rachelnabors commented 4 years ago

I've updated the matrix and moved all the completed components and APIs to a leaderboard to recognize their contributors. Thank you everyone! There's still lots to do: those APIs need love, too!

nnajiabraham commented 4 years ago

Hi @rachelnabors, please can you assign me for all fields on AppRegistry, will update API and write examples 🙌🙌

kaioduarte commented 4 years ago

@rachelnabors I'll take Shadow Props and Text Style Props :wink:

ahmdtalat commented 4 years ago

@rachelnabors update my username in the matrix from (Keyboard) ahmdtalaat -> @ahmdtalat and I need someone to review my PR #1619, thanks.

espipj commented 4 years ago

Appreciate the gifs lol 🦄 @rachelnabors

lfoliveir4 commented 4 years ago

@rachelnabors What do I need to do to finish my contribution with FlatList and if it is possible to update another API or Component?

rachelnabors commented 4 years ago

Matrix is updated! Thanks everyone!

@lfoliveir4 just pick another one and get to it! Flatlist is in the queue. There area lot of PRs to merge. Thank you for your patience!

Simek commented 4 years ago

@rachelnabors Can you claryfiy how you would like to perform changes to deprecated components mentioned in https://github.com/facebook/react-native-website/issues/1579#issuecomment-588361038? I have created an explanation why I'm not sure how to do this properly here: https://github.com/facebook/react-native-website/issues/1579#issuecomment-588812978. If my explanation is still foggy or confusing instead of clarifying I can try explain it again in different words.

facebook / react-native-website

Component Docs Drive #1579

What needs updating?

How to contribute?

Update the API to reflect the props and methods reflected in core

Add missing example code

Embed any example code with a Snack player

Skew on iOS:

Skew on Android:

1626