From f0a213e7bfef5962740c7d55e9a1963ca08ab6bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Kopci=C5=84ski?= Date: Thu, 26 Jun 2025 11:32:43 +0200 Subject: [PATCH 1/5] added REALESE.md and CONTRIBUTING.md files --- .cspell-wordlist.txt | 1 + CONTRIBUTING.md | 90 ++++++++++++++++++++++++++++++++++++++++++++ RELEASE.md | 33 ++++++++++++++++ 3 files changed, 124 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 RELEASE.md diff --git a/.cspell-wordlist.txt b/.cspell-wordlist.txt index 6507c48c27..3742847485 100644 --- a/.cspell-wordlist.txt +++ b/.cspell-wordlist.txt @@ -52,3 +52,4 @@ MPNET QINT FNUZ wordlist +jitpack diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..333e25c71b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,90 @@ +Thank you for your interest in contributing to react-native-executorch! + +# Ways to contribute + +There are several ways you can contribute to react-native-executorch + +- Submit issues related to bugs or desired new features. +- Fix outstanding issues with the existing code. +- Export new models to ET format +- Contribute to examples or to the documentation + +## Submitting a bug-related issue or feature request + +Please try to follow those guidelines when creating issues or feature requests. This makes it easier for us to help you with problems or properly consider your suggestions. +For more general questions and discussions please visit our Discord server. + +## Found a bug? + +Before reporting the issue please check if a similar issue was previously reported, this can be either here or on our Discord server. This will make it much faster for you and us to help you. We prefer you to create issues here on github rather than on Discord as it makes it easier for others to find them later on and makes it easier to include proper context to the problem. When submitting your issue please select a `🐛 Bug` issue template and fill in the required information, this speeds up our responses significantly. + +## Feature request + +Have an idea or is there a feature you would like to see added? Feel free to create a PR from a fork 😉. Alternatively if you don't have time for that just create a `🚀 Feature request` issue and fill in the necessary information. +The most important things to include are: + +1. What is the motivation behind it? Is it something that is missing but is present in another library? Or maybe you need something more specific for your use case? Or just an idea that popped into your head? + We'd love to hear about this! + +2. Describe it - add as much detail as you can. This helps to avoid any miscommunication problems and helps us to better understand it. + +3. Provide a code snippet with the example usage (optional). + +4. If there is a similar feature somewhere else drop a link (optional). + +## Fix outstanding issues + +If you found an issue you would like to tackle and it is not assigned to anyone at the moment feel free to start working on it. Drop a comment under it so that we know it is under progress and then open a PR. For a good starting issue look for `good first issue` label. + +## Export new models to ET format + +Found a model you would like to use in your app but it is not currently supplied by us and got it exported and working with ExecuTorch? We would love you to create a PR on our [🤗 huggingface](https://huggingface.co/spaces/software-mansion/README/discussions?status=open&type=pull_request&sort=recently-created). + +## Contributing to examples or documentation + +Do you have a neat example use case and want to share it with us? You can just drop us a message on Discord server and/or open a PR to `apps` directory here. +If you found some inconsistencies in our documentation or just something is missing just open a PR with suggested changes (remember to add changes to previous docs versions too). + +# Creating a Pull Request + +Before writing any code reach out to us to make sure no one is currently working on it, you can always open an issue first. + +1. Fork the [repository](https://github.com/software-mansion/react-native-executorch) by clicking on the **[Fork](https://github.com/software-mansion/react-native-executorch/fork)** button on the repository's page. This creates a copy of the code under your GitHub use account. + +2. Clone your fork to your local disc, and add the base repository as a remote: + +``` +git clone git@github.com:/react-native-executorch.git +cd react-native-executorch +git remote add upstream https://github.com/software-mansion/react-native-executorch.git +``` + +3. Create you develop branch + +``` +git checkout -b a-descriptive-name-for-my-changes +``` + +🚨 Do not work on the main branch! + +4. Follow installation steps in the [README.md](./README.md) + +5. Develop your code. + To keep your fork up to date run + +``` +git fetch upstream +git rebase upstream/main +``` + +After you are done writing the code push it to the remote + +``` +git push -u origin a-descriptive-name-for-my-changes +``` + +6. Test your changes. + Make sure to test on both Android and IOS. Devices are best, but naturally testing on simulator would be just fine. You can use example apps in the `apps` directory for your testing purposes. + +7. Open a pull request + For details on how to open a pull request from a fork please visit [github's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000000..7603c4c467 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,33 @@ +# General Overview + +## Minor version release + +The release process of new minor version consists of the following steps: + +1. When all tickets tracked in a release tracker (i.e. [#356](https://github.com/software-mansion/react-native-executorch/issues/356)) are merged into main branch, release branch named v{MAJOR}.{VERSION} is cut off from the main branch. +2. Stability tests are performed on the release branch and all fixes to the new-found issues are merged into the main branch and cherry-picked into the release branch. +3. Bump the version inside `package.json` in the root and commit to the release branch with commit message 'release: Bump version to v{MAJOR}.{MINOR}.0`. +4. Tag release branch with proper version tag (v{MAJOR}.{VERSION}.0) and run `npm publish`. +5. Create versioned docs by running from repo root `(cd docs && yarn docusaurus docs:version {MAJOR}.{MINOR}.x)`. +6. Create a PR with updated docs. +7. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. +8. Create release notes on github. + +## Patch release + +After the release branch is created and the version is published to npm we only allow for bug fixes and other critical changes to be included into the release branch. For this purpose we use git `cherry-pick` command. + +1. Create a PR to the main branch. +2. Once the PR is merged, `cherry-pick` the commit to the release branch. +3. Bump the version inside `package.json` in the root and commit to the release branch with commit message 'release: Bump version to v{MAJOR}.{MINOR}.{PATCH}`. +4. Tag release branch with proper version tag (v{MAJOR}.{VERSION}.{PATCH}) and run `npm publish`. +5. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. +6. Create release notes on github. + +## Docs update + +We are using docusaurus with docs versioning. By default when merging PRs with docs changes to the main branch, a github workflow is started to publish the docs. When updating docs the following steps should be considered. + +1. Update the desired doc pages. +2. Check if the changes are applicable to past versions, if so make the same updates to the correct files in versioned docs inside `react-native-executorch/docs/versioned_docs/version-{MAJOR}.{MINOR}.x`. +3. Create a PR to the main branch. From e3962ffe726f9252964a7faa3a427c312e19b9fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Kopci=C5=84ski?= Date: Mon, 30 Jun 2025 12:30:04 +0200 Subject: [PATCH 2/5] REALESE.md changes --- RELEASE.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 7603c4c467..ad63e45933 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -4,14 +4,20 @@ The release process of new minor version consists of the following steps: -1. When all tickets tracked in a release tracker (i.e. [#356](https://github.com/software-mansion/react-native-executorch/issues/356)) are merged into main branch, release branch named v{MAJOR}.{VERSION} is cut off from the main branch. -2. Stability tests are performed on the release branch and all fixes to the new-found issues are merged into the main branch and cherry-picked into the release branch. -3. Bump the version inside `package.json` in the root and commit to the release branch with commit message 'release: Bump version to v{MAJOR}.{MINOR}.0`. -4. Tag release branch with proper version tag (v{MAJOR}.{VERSION}.0) and run `npm publish`. -5. Create versioned docs by running from repo root `(cd docs && yarn docusaurus docs:version {MAJOR}.{MINOR}.x)`. -6. Create a PR with updated docs. -7. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. -8. Create release notes on github. +1. Merge all tickets tracked in a release tracker (i.e. [#356](https://github.com/software-mansion/react-native-executorch/issues/356)) into `main` branch. +2. Bump version in `package.json` to the new version `v{MAJOR}.{MINOR}.0`. +3. Update jitpack version inside `build.gradle` to point to the correct version tag + ``` + implementation("com.github.software-mansion:react-native-executorch:v{MAJOR}.{MINOR}.{REVISION}") + ``` +4. Commit with a message 'Release v{MAJOR}.{MINOR}.0'. (We want to keep the latest `MINOR` version on the `main` branch.) +5. Create a new branch release branch `release/{MAJOR}.{MINOR}`and push it to the remote. +6. Stability tests are performed on the release branch and all fixes to the new-found issues are pushed into the main branch and cherry-picked into the release branch. This allows for further development on the main branch without interfering with the release process. +7. Once all tests are passed, tag the release branch with proper version tag `v{MAJOR}.{MINOR}.0` and run `npm publish`. +8. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. +9. Create versioned docs by running from repo root `(cd docs && yarn docusaurus docs:version {MAJOR}.{MINOR}.x)` (the 'x' part is intentional and is not to be substituted). +10. Create a PR with the updated docs. +11. Create the release notes on github. ## Patch release @@ -19,8 +25,13 @@ After the release branch is created and the version is published to npm we only 1. Create a PR to the main branch. 2. Once the PR is merged, `cherry-pick` the commit to the release branch. -3. Bump the version inside `package.json` in the root and commit to the release branch with commit message 'release: Bump version to v{MAJOR}.{MINOR}.{PATCH}`. -4. Tag release branch with proper version tag (v{MAJOR}.{VERSION}.{PATCH}) and run `npm publish`. +3. Bump version in `package.json` to the new version `v{MAJOR}.{MINOR}.{REVISION}`. + Update jitpack version inside `build.gradle` to point to the correct version tag + ``` + implementation("com.github.software-mansion:react-native-executorch:v{MAJOR}.{MINOR}.{REVISION}") + ``` + Commit with a message 'Release v{MAJOR}.{MINOR}.0'. +4. Tag release branch with proper version tag `v{MAJOR}.{MINOR}.{REVISION}` and run `npm publish`. 5. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. 6. Create release notes on github. From 1b91fc82b2f250bc32e12923214de3c2c4b863c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Kopci=C5=84ski?= Date: Mon, 30 Jun 2025 12:59:47 +0200 Subject: [PATCH 3/5] review changes --- CONTRIBUTING.md | 7 ++++--- RELEASE.md | 6 +++++- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 333e25c71b..f81db93497 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ For more general questions and discussions please visit our Discord server. ## Found a bug? -Before reporting the issue please check if a similar issue was previously reported, this can be either here or on our Discord server. This will make it much faster for you and us to help you. We prefer you to create issues here on github rather than on Discord as it makes it easier for others to find them later on and makes it easier to include proper context to the problem. When submitting your issue please select a `🐛 Bug` issue template and fill in the required information, this speeds up our responses significantly. +Before reporting the issue please check **if a similar issue was previously reported** (use the search bar on GitHub under Issues). This will make it much faster for you and us to help you. We prefer you to create issues here on github rather than on Discord as it makes it easier for others to find them later on and makes it easier to include proper context to the problem. When submitting your issue please select a `🐛 Bug` issue template and fill in the required information, this speeds up our responses significantly. ## Feature request @@ -59,13 +59,14 @@ cd react-native-executorch git remote add upstream https://github.com/software-mansion/react-native-executorch.git ``` -3. Create you develop branch +3. Create your develop branch ``` git checkout -b a-descriptive-name-for-my-changes ``` -🚨 Do not work on the main branch! +> [!CAUTION] +> Do not work on the main branch! 4. Follow installation steps in the [README.md](./README.md) diff --git a/RELEASE.md b/RELEASE.md index ad63e45933..b85d5c6ffe 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -23,6 +23,9 @@ The release process of new minor version consists of the following steps: After the release branch is created and the version is published to npm we only allow for bug fixes and other critical changes to be included into the release branch. For this purpose we use git `cherry-pick` command. +> [!CAUTION] +> Those changes should NOT include documentation changes, as they would be released automatically on the PR's merge and before the code changes are live. Instead create a separate PR with doc changes according to the [Docs update](#docs-update) section. + 1. Create a PR to the main branch. 2. Once the PR is merged, `cherry-pick` the commit to the release branch. 3. Bump version in `package.json` to the new version `v{MAJOR}.{MINOR}.{REVISION}`. @@ -37,7 +40,8 @@ After the release branch is created and the version is published to npm we only ## Docs update -We are using docusaurus with docs versioning. By default when merging PRs with docs changes to the main branch, a github workflow is started to publish the docs. When updating docs the following steps should be considered. +We are using docusaurus with docs versioning. By default when merging PRs with docs changes to the main branch, a github workflow is started to publish the docs. For this reason those changes should be merged only once the related changes are released. +When updating docs the following steps should be considered. 1. Update the desired doc pages. 2. Check if the changes are applicable to past versions, if so make the same updates to the correct files in versioned docs inside `react-native-executorch/docs/versioned_docs/version-{MAJOR}.{MINOR}.x`. From cb04d5d7c70585f963fdf41c6101ae596ca7fc7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Kopci=C5=84ski?= Date: Mon, 30 Jun 2025 14:46:08 +0200 Subject: [PATCH 4/5] review fixes --- CONTRIBUTING.md | 6 +++--- RELEASE.md | 23 ++++++++++++----------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f81db93497..28c48957f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,11 +16,11 @@ For more general questions and discussions please visit our Discord server. ## Found a bug? -Before reporting the issue please check **if a similar issue was previously reported** (use the search bar on GitHub under Issues). This will make it much faster for you and us to help you. We prefer you to create issues here on github rather than on Discord as it makes it easier for others to find them later on and makes it easier to include proper context to the problem. When submitting your issue please select a `🐛 Bug` issue template and fill in the required information, this speeds up our responses significantly. +Before reporting the issue please check **if a similar issue was previously reported** (use the search bar on GitHub under Issues). This will make it much faster for you and us to help you. We prefer you to create issues here on GitHub rather than on Discord as it makes it easier for others to find them later on and makes it easier to include proper context to the problem. When submitting your issue please select a `🐛 Bug` issue template and fill in the required information, this speeds up our responses significantly. ## Feature request -Have an idea or is there a feature you would like to see added? Feel free to create a PR from a fork 😉. Alternatively if you don't have time for that just create a `🚀 Feature request` issue and fill in the necessary information. +Have an idea or is there a feature you would like to see added? This can be a specific model, an entire model family, a code functionality or anything else you think might be useful. Feel free to create a PR from a fork 😉. Alternatively if you don't have time for that just create a `🚀 Feature request` issue and fill in the necessary information. The most important things to include are: 1. What is the motivation behind it? Is it something that is missing but is present in another library? Or maybe you need something more specific for your use case? Or just an idea that popped into your head? @@ -43,7 +43,7 @@ Found a model you would like to use in your app but it is not currently supplied ## Contributing to examples or documentation Do you have a neat example use case and want to share it with us? You can just drop us a message on Discord server and/or open a PR to `apps` directory here. -If you found some inconsistencies in our documentation or just something is missing just open a PR with suggested changes (remember to add changes to previous docs versions too). +If you found some inconsistencies in our documentation or just something is missing just open a PR with suggested changes (remember to add changes to previous docs versions too, e.g `docs/versioned_docs/version-0.3.x`, `docs/versioned_docs/version-0.4.x`). # Creating a Pull Request diff --git a/RELEASE.md b/RELEASE.md index b85d5c6ffe..baa7619ea6 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -6,18 +6,19 @@ The release process of new minor version consists of the following steps: 1. Merge all tickets tracked in a release tracker (i.e. [#356](https://github.com/software-mansion/react-native-executorch/issues/356)) into `main` branch. 2. Bump version in `package.json` to the new version `v{MAJOR}.{MINOR}.0`. -3. Update jitpack version inside `build.gradle` to point to the correct version tag +3. Update version tags in `packages/react-native-executorch/src/constants/modelUrls.ts` to point to the proper `MINOR` version and update tags on [🤗 huggingface](https://huggingface.co/software-mansion). +4. Update jitpack version inside `build.gradle` to point to the correct version tag ``` implementation("com.github.software-mansion:react-native-executorch:v{MAJOR}.{MINOR}.{REVISION}") ``` -4. Commit with a message 'Release v{MAJOR}.{MINOR}.0'. (We want to keep the latest `MINOR` version on the `main` branch.) -5. Create a new branch release branch `release/{MAJOR}.{MINOR}`and push it to the remote. -6. Stability tests are performed on the release branch and all fixes to the new-found issues are pushed into the main branch and cherry-picked into the release branch. This allows for further development on the main branch without interfering with the release process. -7. Once all tests are passed, tag the release branch with proper version tag `v{MAJOR}.{MINOR}.0` and run `npm publish`. -8. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. -9. Create versioned docs by running from repo root `(cd docs && yarn docusaurus docs:version {MAJOR}.{MINOR}.x)` (the 'x' part is intentional and is not to be substituted). -10. Create a PR with the updated docs. -11. Create the release notes on github. +5. Commit with a message 'Release v{MAJOR}.{MINOR}.0'. (We want to keep the latest `MINOR` version on the `main` branch.) +6. Create a new branch release branch `release/{MAJOR}.{MINOR}`and push it to the remote. +7. Stability tests are performed on the release branch and all fixes to the new-found issues are pushed into the main branch and cherry-picked into the release branch. This allows for further development on the main branch without interfering with the release process. +8. Once all tests are passed, tag the release branch with proper version tag `v{MAJOR}.{MINOR}.0` and run `npm publish`. +9. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. +10. Create versioned docs by running from repo root `(cd docs && yarn docusaurus docs:version {MAJOR}.{MINOR}.x)` (the 'x' part is intentional and is not to be substituted). +11. Create a PR with the updated docs. +12. Create the release notes on GitHub. ## Patch release @@ -36,11 +37,11 @@ After the release branch is created and the version is published to npm we only Commit with a message 'Release v{MAJOR}.{MINOR}.0'. 4. Tag release branch with proper version tag `v{MAJOR}.{MINOR}.{REVISION}` and run `npm publish`. 5. Ensure [jitpack](https://jitpack.io/#software-mansion/react-native-executorch) triggers build properly. -6. Create release notes on github. +6. Create release notes on GitHub. ## Docs update -We are using docusaurus with docs versioning. By default when merging PRs with docs changes to the main branch, a github workflow is started to publish the docs. For this reason those changes should be merged only once the related changes are released. +We are using docusaurus with docs versioning. By default when merging PRs with docs changes to the main branch, a GitHub workflow is started to publish the docs. For this reason those changes should be merged only once the related changes are released. When updating docs the following steps should be considered. 1. Update the desired doc pages. From 515344df30f0ef8ae143c708c16146aac5d25439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Kopci=C5=84ski?= Date: Mon, 30 Jun 2025 14:51:19 +0200 Subject: [PATCH 5/5] added step 13 --- RELEASE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASE.md b/RELEASE.md index baa7619ea6..050a0dd432 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -19,6 +19,7 @@ The release process of new minor version consists of the following steps: 10. Create versioned docs by running from repo root `(cd docs && yarn docusaurus docs:version {MAJOR}.{MINOR}.x)` (the 'x' part is intentional and is not to be substituted). 11. Create a PR with the updated docs. 12. Create the release notes on GitHub. +13. Update README.md with release video, if available. ## Patch release