Known issues

[kelset]

Intro

This discussion was born in the RN core team, but since the discussion was fairly recent and lengthy we thought that moving it to an issue would be the best first step to reset our minds about it.

The Gist of it

React Native is has a lot of moving parts, and they all are slightly non-perfect: sometimes these bugs and limitations are not solvable in the short/medium term, so workarounds may be necessary. Or, at least, there should be "easy to reach" knowledge for everyone to know and not waste N hours in vain.

This is the "known issue" definition we agreeded on:

is a way more relaxed interpretation of the word issue: it is something that you will face when using React Native that may or may not be a bug, and is may not be caused by React Native. And when there is a known issue usually I can also expect a workaround to be written there.

What we want to solve is the when/where/how of this broader exposition of known issues, in order to avoid:

1. creating confusion/panic
2. creating too much overhead of work for maintainers

This would also double to help show gaps in the test suite.

Currently, we have a set of labels related to “components or families of components”, and those are indicated by the 🔶 emoji. But it's not covering all the components. And those issues are not all "known issues".

Remembering that it’s possible to give multiple tags to issues and even filter for multiple tags, some ideas have been proposed.

Approach A: issues are the focus

We do PRs to the docs, and to each component page we add a phrase like “To see how this component performs in the wild, you can check its related open issues in the repo” and we link to the open issues with:

Proposal 1

A new label created appositely "Known issue" + the component related label.
This would require the integration of the current list 🔶 emoji with (at least) all the other components listed in the left panel in the docs.

Proposal 2

A new set of label that will mimick 1:1 all the components listed in the left panel in the docs.

Approach B: documentation is the focus

In this scenario, every known issue will be present in the dedicated doc page for that component, in a section like:

## InputAccessoryView known issues

- [Doesn't support multiline `TextInput`s](https://github.com/facebook/react-native/issues/18997)
- [Can't use with a bottom tab bar](https://github.com/facebook/react-native/issues/20157)

With link to an eventual issue in the main repo, if it exists.

This is the closest approach to what happens currently, where usually PRs are submitted to docs to inform about "known issues" for specific things.

---

For some context, here are some issues that would fit the status of "known issue":

• Problem when you want to upgrade gradle and it doesnt to download. facebook/react-native-website#425
• Can't run jest tests with 0.56.0 facebook/react-native#19859 (comment)
• https://facebook.github.io/react-native/docs/textinput#value
• [InputAccessoryView] Can't specify keyboard-conditional bottom padding facebook/react-native#20157
• InputAccessoryView doesn't update its height when multiline TextInput grows in height facebook/react-native#18997

---

What should be the "final" approach in solving this? Let's discuss!

[Ashoat]

First of all, @kelset thanks a lot for taking the time to compose this issue and summarize the discussion. Really appreciate the work you do for the community!

The only one of these proposals I am opposed to is A1. My concern is that in that world, since some components will be sharing labels, the "known issue" links on their docs page may list issues that actually don't concern the component in question. I think this will have two negative effects:

1. Accidentally dissuading the user from using a component or even React Native. It's true that if the user reads through the issues they can figure out which of them are relevant, but it's not always immediately obvious from the title of an issue, and sometimes a long list of issues is enough to scare somebody.
2. Making the user distrust the list of "known issues", since in many cases the signal-to-noise ratio will be too low. If there are tons of known issues that aren't relevant to a specific component, the reader may end up concluding that the list isn't maintained or is simply inaccurate, and will not want to consult it again.

Consequently my preference is either for A2 or B. I think A2 would be less work overall, but B is probably overall "better". Coupling the "known issues" to "GitHub issues" is a little unideal, largely because the two have different motivations. Besides the question of label clutter, the titles are aimed at different audiences.

As an example, I titled the GitHub issue facebook/react-native/issues/20157 as "[InputAccessoryView] Can't specify keyboard-conditional bottom padding", since that describes the problem concisely and precisely. But it doesn't cover the implications to users. If I was titling the same issue from a "known issues" perspective, I would say "[InputAccessoryView] Impossible to use with bottom tab bar", because that's the relevant implication to a product engineer.

[franzejr]

Thanks, @kelset for opening this conversation!

This is the kind of thing I've been thinking for some time. I agree with @Ashoat that the approach A1 might be dissuading and hard to track which component is the problem. We will potentially have issues with two components or more, making really hard to track it.

I'd vote for A2 or B, especially the B.

[kelset]

Hey everyone, thanks for the feedback and sorry if it took me so long to reply back.

I also think that we should proceed towards the solution B.

Or, to be honest, by pondering about the pre-issue discussion and investigation of the open issues, I believe we should do 3 things:

1. enhance the list of 🔶 labels to cover better the components spectrum (for better maintainance)
2. create a "known issue" label for github, because that would help me (and other maintainers) to quickly filter them out and, by providing a good description for the label, communicate to the users that they should do a PR towards the doc to write about it in a concise way (if possible).
3. write the known issues per component with "standardized template" at the bottom of each component's section.

In particular, about the third bullet point, I think that the next "actual" step would be to open an issue on the react-native-website with an example template and the list of known issues separated by component, so that they can be picked up separately by multiple people and create some easy PRs to introduce members to being part of the Open Source comm.

What do you think?

[franzejr]

I liked that @kelset

[Ashoat]

Sounds good! I think the hard part is gonna be combing through open GitHub issues in order to pull together the full list of known issues. There’s almost 700 open issues now.

I’ll have time in early Sept to help go through that list, but I’m pretty busy up through this Thursday, when I’ll be going off-grid until Sept.

Do you guys think we should start the process of pulling together a template first, and maybe we can go component-by-component so we can break up the work into chunks?

[kelset]

Glad to hear that :)

I think that yes, we should start by

process of pulling together a template first,

And then I don't think this needs to be "retroactive", meaning that I don't think this

combing through open GitHub issues in order to pull together the full list of known issues

is a hard requirement.

We can start with the shortlist of stuff and then parse through the issues over time, no rush :)

[sahrens]

This is great, thanks for spearheading. I look forward to seeing progress. Let me know if you are blocked on FB for anything.

[axe-fb]

@kelset - pinging to see what we can do to move the proposal forward.

[kelset]

@Ashoat is already moving it forward, he did create a PR to test the change here: facebook/react-native-website#519 and also created a gist drafting the text for the issue we are going to open on the repo.

but he's the one mostly working on it and he's on holiday now, and I'm still mostly focusing on the 0.57.0 atm.

[Ashoat]

I’m back! Will work on pushing this forward.

[kelset]

Closing in favour of the issue that @Ashoat opened in the website repo - thanks everyone for the feedback and discussion :)