React: Write a contribution guide documenting the design decisions

[gaearon]

Historically we haven’t been very good at explaining how to contribute to React.
We have a small guide but it doesn’t offer crucial information about:

• Our build process and providesModule.
• Design constraints that guide what gets in and what doesn’t.
• Conventions like invariant, warning, __DEV__, and infra around them.
• How we introduce breaking changes and deprecations.
• How syncing with React Native and Facebook website affects contributions.
• Basic directory organization, what can or can’t go in either directory.
• Unfortunate decisions in the codebase that we want to get away from.
• What is being actively worked on, and why.
• An internal glossary:
  
  
  
  • Elements
  
  
  • Public instances
  
  
  • Internal instances
  
  
  • Composite components
  
  
  • Native components
  
  
  • Reconciliation
  
  
  • Transactions
  
  
  • Update queue
  
  
  • Synthetic events
  
  

What do you think? I’m especially interested in hearing from people who considered contributing to React but were turned away by the internal complexity.

[sophiebits]

Some incoherent notes I made earlier about design philosophy:

• no global config (ex: events, dangerouslySetInnerHTML)
• abstractions that scale (no .reactTarget)
• benchmarking the right thing
• don't put things in the core if they don't need to be
• but we're moving Flux into the core (maybe)
• simple > easy? (e.g., cursor in controlled components)
• server rendering vs service workers
• optimize for readability/greppability (lifecycle names)
• APIs that accept too-liberal data (e.g., nulls) are not helpful in the long run

[aweary]

I've been looking for a good high level overview on how all the React internals work together, so if this could include something like that as well I think it'd be really helpful.

[sebmarkbage]

• Things that break encapsulation or potentially leaking implementation details across levels of components.
• Favor modularity and ability to build it outside React (e.g. as a component) - unless it is something that we expect most apps to have to build. E.g. component state.

[gaearon]

Commonly requested: an explanation of what happens when you call setState(), from start to end. Granted, this can change between releases, but a high level overview of the process would improve contributors’ understanding quite a bit.

[jide]

Things I have asked myself when trying to understand, and contribute to, the codebase... It's probably a lot, but costs nothing to lay them here :)

• How things flow on mount / update ?
• What really is and how transaction and reconciliation do work ?
• Why the use of Mixins and all ? And inconsistencies regarding these ?
• Why the use of globals ? How globals work ?
• Why are react-dom and react so tightly coupled and insights on how the concept of renderer works ?
• How injection works ?
• What are parts that have been written in the goal of being performant at the cost of being dense / ugly ?

[kentcdodds]

Everything mentioned looks great! I definitely feel like adding react-specific contributing documentation is a must to help people contribute.

I also believe that making things beginner friendly is valuable. There are people who want to contribute and can, but they're not familiar with git or GitHub and may not even know what a Pull Request is.

Even though it's technically not the React team's responsibility to teach people these fundamental concepts, I think leading out with some good solid resources that do would be really helpful. This is the main motivation behind #6332 and #6333.

Either way, thanks for giving thought to making it easier to contribute to React. This project can be a good example for other projects in the community!

[jide]

The overall impression I got while reading the codebase is that if it was not facebook's, I'd have thought it was hard to read, and full of hackish things and inconsistencies... But I know some great engineers have written the codebase :) so there must be valid (or not !) reasons for this, be it historic, performance, architecture opinion, backward compat... It would be great to know more on the general history of this code.

I also realized recently that react-native was written in a very different way, more modern, and I'd like to know more about the plans regarding the 2 projects.

[sophiebits]

In what ways is React Native more modern? Lots of it builds on top of React so is a little higher-level but otherwise I tend to think the coding styles are similar.

[jide]

I find the folder structure much easier to follow for example, and I found it has less inconsistencies, but I'm not too familiar with the react native codebase.

[jide]

But it may not make sense to compare them.

[gaearon]

I agree with @jide that internal reliance on mixins (e.g. ReactMultiChild) and injection are confusing. I don’t want this thread to become a place to bikeshed on different internal complexities but we definitely want to document the high level ideas behind the code organization and how we split module responsibilities, as well as some historical context behind that.

[slorber]

I'd like to contribute to the core of React (or at least understand it), but found it hard to approach. Taking a quick look at it discouraged me and I felt I only had time to contribute on minor fixes, documentation or github issues.

I'd like a guide yes!

[zrosenbauer]

@gaearon I think that list would REALLY help (at least me) as it's pretty difficult to jump into a project without some good notes to guide you as I personally cannot take the many hours it takes to read all the code and reason about how the sys works....well at least not yet...I should be taking a vacation here soon maybe then.... :smile:

[nhunzaker]

but we're moving Flux into the core (maybe)

@spicyj I don't want to steer too off topic but is it possible to elaborate or link to more thoughts here?

[sophiebits]

@nhunzaker #4595 has some related discussion. Nothing decided yet.

[resistdesign]

What would be contributed? Does React really _need_ more?

[eanplatter]

On one of my projects we had talked about creating a sort of README for contributing _(different from contributing guides, which seem to focus more on general things like code conventions and project philosophies)_, which kind of turned into a walkthrough of the codebase. I've got a PR proposal on the project with a section of what the walkthrough could look like here: https://github.com/eanplatter/enclave/pull/88.

Sometimes when you're looking at unfamiliar patterns it's hard to tell vital organs from sinews.

I am also the type of person who learns best from macro to micro, so a birds-eye view of the project seemed helpful to me.

[cbrwizard]

I've just started contributing (2 accepted PRs about tests so far) and the more information there is about the code - the better! Check out Eslint Developer Guide for an example. When I read it I started having a much better understanding of their code.
Yes, it will require effort and time to write and maintain. However, since React is a very popular library and open source, I think it's worth it. What's more, it will help identify the current issues with the code and maybe give an idea on how to optimize it.

[DjebbZ]

Aldo explains how to contribute documentation, how the website is built, how JSX is properly highlighted in code snippets (big struggle for me). I love to contribute documentation but didn't understand how to do it here.

[DjebbZ]

And how to make sure doc is properly indexed by Algolia and the search bar (great addition by the way!)

-- sorry for the double comment, the mobile version of GH doesn't have an edit button.

[gaearon]

We started something here:

https://facebook.github.io/react/contributing/design-principles.html

I will add more content in the coming days.

[gaearon]

I published some more information.

How to Contribute is what we used to have in CONTRIBUTING.md, but more up-to-date, and with new tips like how to test your changes to React locally.

Codebase Overview documents our conventions and walks you through how the codebase is split and organized.

Let me know what you think!

[zrosenbauer]

👍 hacktoberfest is coming... so timing is perfect. Thanks @gaearon.

[gaearon]

Detailed Implementation Notes are up. They detail (in a somewhat simplified way) how the stack reconciler works.

I believe this, together with How to Contribute, Codebase Overview, and Design Decisions covers most of the ground here.

I likely won't have the time to cover more, but this should give somebody motivated enough information to contribute, e.g. a glossary.