How should be the proper way to stay updated with new releases?

[Guuri11]

Hi there!

first of all, I hope you doing great & congrats for the ui lib, it's great! I wanted to know if there are some guidelines about how to update properly the library to future new releases. For example, guides about deprecrations, breaking changes, new components, etc...

Thanks!

[mrzachnugent]

Hey @Guuri11 , what could I provide that would help you the most?

I need to improve on this aspect as there's no "proper way" to stay up to date. As react 19 is approaching, there will be a lot of changing coming up so I really need to start taking this seriously.

[Guuri11]

It would be great, maybe we could have some conversation about how to document the next major release based on how it should be done from a project already with the previous version. In the end it is always very easy to leave it ready for projects that start again, but it is important that the current ones survive and be updated easily, it sure adds a lot for the community to support the library even more, it has a lot of potential :)

[Guuri11]

here are some tips (by chatgpt XD) about how to have a scalable versioning system for your lib:

---

(chatgpt)

Since it's a React Native library, the context is a bit more specific—you're in the JS/TS ecosystem, mobile-focused, and usually working with people who expect smooth upgrades across versions. Here’s how I’d approach versioning and upgrade experience for your library, step by step:

---

🔢 1. Use Semantic Versioning (SemVer) Properly

Stick to the classic format:
MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (API change, behavior change, etc.)
• MINOR: Backward-compatible features or improvements
• PATCH: Bug fixes, internal changes

✅ You can even use tools like [standard-version](https://github.com/conventional-changelog/standard-version) to automate versioning and changelog creation based on commit messages.

---

⚠️ 2. Deprecation Strategy

This is super important in open-source or shared libraries:

• Use console.warn() to alert developers during development that a method is deprecated.
• Clearly mark deprecated methods in your TypeScript types using /** @deprecated Use newMethod instead */.
• Provide migration guidance (ideally in your changelog and docs).
• Give developers at least one minor version to adapt before removing deprecated code.

💡 If you're using TypeScript, VSCode and other editors will display deprecated warnings automatically.

---

📘 3. Keep a Clear and Human-Readable Changelog

Maintain a CHANGELOG.md file that explains what changed, why, and what to do about it:

Example:

## [1.2.0] - 2025-04-04
### Added
- New `useAwesomeHook()` for easier state tracking.

### Deprecated
- `useOldHook()` is deprecated. Use `useAwesomeHook()` instead.

### Fixed
- Crash on Android when rotating the screen.

You can use [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) style to stay consistent.

---

🧪 4. Regression & Compatibility Tests

Make sure your test suite covers real usage scenarios.

• If possible, use something like [React Native Testing Library](https://callstack.github.io/react-native-testing-library/) to write tests that simulate how users integrate your library.
• Add tests for deprecated functions to ensure they still work (until they’re removed).

---

🚨 5. Highlight Breaking Changes

When making a major version bump (e.g., v2.0.0), be very loud about:

• What changed
• Why it changed
• How to migrate

Bonus points if you provide:

• Code examples before and after
• A migration guide
• Maybe even a codemod or upgrade script if it's a big change

---

🛠 6. Developer Tooling

Make it easy for devs to upgrade:

• Publish TypeScript types (helps with DX and catching issues).
• Publish your package via ESM + CJS if applicable.
• Use [peerDependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) correctly for React Native / React versions.

---

💡 Bonus: Communicate Effectively

• Use GitHub releases to document each version.
• Tweet, post, or share changelogs in Discord/Slack if you have a community.
• Document upgrade paths clearly in your README or docs site.

---

If you want, I can help you:

• Set up a CHANGELOG.md template
• Write a sample migration guide
• Define commit conventions to automate changelog + versioning
• Or even review your deprecation messages

---

(end)

Btw, here you have some posts about the topic that maybe is helpful

https://dev.to/igbikisimewari/best-version-control-practices-every-react-development-team-needs-to-know-hee
https://www.reddit.com/r/react/comments/1bcfzlf/whats_a_good_robust_open_source_react_codebase/
https://www.reddit.com/r/opensource/comments/1feawag/best_way_to_make_a_document_opensource_with_a/
https://blog.pixelfreestudio.com/the-role-of-version-control-in-open-source-projects/
https://themobilereality.com/blog/how-to-write-a-good-documentation-for-your-open-source-library-2022-updated
https://www.youtube.com/watch?v=MxGYZ-hr3f0&ab_channel=Nearform

[MrPiao]

I'm spitballing here, and this is not really backwards compatible, but here is a somewhat simple idea:

1. When the CLI is used to add a component to the project, also create / modify a json file (maybe use the components.json that is already created) to record what version of a specific component has been added.
2. When the CLI is used to update components, diff the new component with the old component (of the specified version) and warn the user if there are modifications. The user can then choose to overwrite or figure it out.

The biggest problem I see with this approach is that some people (read: me 😂) just let eslint/prettier lint the file after it is added to make the linter errors go away instead of exempting the path from linters. So if I were to use this update feature I would have to manually apply all of the custom changes I have anyways.

Which might be ok. I think the strength of RNR is the simplicty and the customizability of it, so the fact that a major update (like React 19 compatibility) doesn't automagically update around your modifications is expected.

[sgurillogbe]

Hey @mrzachnugent , @MrPiao

I really like the idea of having some form of version tracking per component, especially if it's integrated into the CLI. Even if it’s not perfect due to custom edits or linting, it’s still better than having no guidance at all when updating.

Maybe it could be a bit tricky to make it fully reliable, so maybe something opt-in or even just a tool to suggest what might have changed would already be super helpful.

I’d also love to see something like:

A clear changelog per version (especially calling out breaking changes or deprecations or references from official shadcn docs).

A migration guide when a major version is released, even short but focused on real-world projects.

Tagging PRs or releases with [breaking], [deprecation], etc., could really help organize this better going forward.

The library has great potential, and making it easier to maintain and upgrade over time would definitely make the community stronger 🙌

[LuksGabb]

Hey @mrzachnugent

any update/thoughts on this ?