The Basics and Guides should not be versioned

[hramos]

We currently allow readers to switch the website version. This lets them see the docs as a snapshot for a given React Native release. For example, what were the APIs for ScrollView back in 0.20 versus 0.50?

Our goal with the content in The Basics and Guides is to provide information that is relevant today, with the assumption that the user is on the latest release.

In order to make this work under our versioning infrastructure*, we've had to place this content in website/versioned_docs/version-0.5, e.g. the oldest public release. By doing so, we're always serving the freshest version of these guides, but we also add some friction as people will need to edit two files (those in docs/ as well as website/versioned_docs/version-0.5) to ensure the edits are not lost when a new release is cut.

We can easily fix this by adding a script that syncs edits made to these specific files. With that in place, we only need to tell our readers to edit the files in docs/ and to ignore anything in website/versioned_docs/.

The list of files that would need to be synced are (as gleaned from sidebars.json):

The Basics

• docs/getting-started.md
• docs/tutorial.md
• docs/props.md
• docs/state.md
• docs/style.md
• docs/height-and-width.md
• docs/flexbox.md
• docs/handling-text-input.md
• docs/handling-touches.md
• docs/using-a-scrollview.md
• docs/using-a-listview.md
• docs/network.md
• docs/more-resources.md

Guides

• docs/components-and-apis.md
• docs/platform-specific-code.md
• docs/navigation.md
• docs/images.md
• docs/animations.md
• docs/accessibility.md
• docs/improvingux.md
• docs/timers.md
• docs/debugging.md
• docs/performance.md
• docs/gesture-responder-system.md
• docs/javascript-environment.md
• docs/direct-manipulation.md
• docs/colors.md
• docs/integration-with-existing-apps.md
• docs/running-on-device.md
• docs/upgrading.md
• docs/troubleshooting.md

Guides (iOS)

• docs/native-modules-ios.md
• docs/native-components-ios.md
• docs/linking-libraries-ios.md
• docs/running-on-simulator-ios.md
• docs/communication-ios.md
• docs/building-for-apple-tv.md
• docs/app-extensions.md

Guides (Android)

• docs/native-modules-android.md
• docs/native-components-android.md
• docs/headless-js-android.md
• docs/signed-apk-android.md
• docs/android-building-from-source.md

Contributing

• docs/contributing.md
• docs/maintainers.md
• docs/testing.md
• docs/understanding-cli.md

• When versioning is enabled, as is the case for this site, the static site generator does not actually serve content from the docs/ folder. Instead, it will go through each sub-directory in website/versioned_docs until it finds the most recent version-* directory that contains the requested document. In this manner, we always serve the most recent version of the doc. Whenever a new version is cut, we check against docs/ and only copy over those files that have changed. This is why these evergreen files listed above are all placed in website/versioned_docs/version-0.5 even though they've all seen multiple edits since version 0.5 - they were manually placed there.

[Jeanmsilva89]

I noticed that the Assets in the docs directory is not versioned. I think it would be important to version assets/images for consistency. I'm happy to submit a PR for it if this is desired. Thanks!

@hramos @cpojer: I'm tagging you guys here since this is an old issue and it might not be coming up to you guys and I didn't think it would be worth creating a new issue, plus this provides context to the initial setup.

[chrisbobbe]

In docs/integration-with-existing-apps.md, under "Configuring CocoaPods dependencies", the example Podfile in /ios differs by version. A side effect of not versioning that doc is that people will be given an incorrect example for their version; I suspect this is a cause of #1194.

EDIT: Looks like this is open as #1603.

EDIT: See #1603 (comment), which may resolve this concern, but only once the change in 53cd8f6 is published; it hasn't been as of this post.

EDIT (again, sorry): Actually, it probably doesn't resolve it; see that same comment. v0.59 users will still be without an example Podfile; it seems the only record of the official example Podfile for v0.59 is that file at ded79d2cf

[cHaLkdusT]

I think it's better to "version" all files because we have users who can't afford to upgrade yet. So relying on old documentation is still relevant to them.

[stale]

👋 Hey there, it looks like there has been no activity on this issue recently. Has the issue been fixed, or does it still require the community's attention? This issue may be closed if no further activity occurs. Thank you for your contributions.

[stale]

Closing this issue after a prolonged period of inactivity. If this issue is still present in the latest release, please feel free to create a new issue with up-to-date information.