[BFCL] Guide to Major Release with Breaking API Changes

[devanshamin]

Summary of Steps for Merging PR #510

1. Split Subfolder into Separate Branch:

   • Clone the Gorilla repository.
   • Use git subtree split to create a new branch for berkeley-function-call-leaderboard while preserving commit history.

2. Create New Repository:

   • Clone the new branch.
   • Rename the repository and push to a new remote (bfcl).

3. Set Up Releases:

   • Tag the initial release in the new repository and push the tag.

4. Add bfcl as a Submodule:

   • Create a new branch in the Gorilla repository.
   • Remove the original berkeley-function-call-leaderboard subfolder.
   • Rewrite history to remove subfolder commits.
   • Add bfcl as a submodule and commit the changes.

5. Update Submodule Periodically:

   • Checkout the desired release in the submodule.
   • Commit and push the submodule update.

End Product

• BFCL Repository
• Gorilla Repository with Submodule

Approach on Merging PR #510

Note: Replace my github username devanshamin with ShishirPatil and execute the steps.

Step 1: Split the gorilla/berkeley-function-call-leaderboard Subfolder into a Separate Branch While Preserving the Commits

$ git clone https://github.com/devanshamin/gorilla.git
$ git subtree split -P berkeley-function-call-leaderboard -b bfcl_main
$ git log --oneline -5
86278da (HEAD -> bfcl_main) [BFCL] Fix Possible Answer for AST Parallel and Parallel_Multiple Category (#503)
ecc2603 [BFCL] Improved tree-sitter java, javascript installation (#505)
bedbc65 [BFCL] Sanity check is now optional (#496)
2f0c882 [BFCL] Add Support for GLM-4-9B function calling inference (#474)
e213339 fix some data issues in parallel/parallel multiple answers (#423)

Step 2: Move the gorilla/berkeley-function-call-leaderboard Subfolder with Commits to a New Repository

$ git clone https://github.com/devanshamin/gorilla.git -b bfcl_main
# [Optional] Rename the `gorilla` repository/directory to `bfcl`
$ git remote set-url origin https://github.com/devanshamin/bfcl.git
$ git branch -M main
$ git push -u origin main

Step 3: Set Up Releases in the New Repository

$ git tag -a v0.1.0 -m "Initial release v0.1.0"
$ git push origin v0.1.0

Now, you will have the existing codebase of gorilla/berkeley-function-call-leaderboard packaged and available as v0.1.0 for backward compatibility:

git clone -b v0.1.0 https://github.com/devanshamin/bfcl.git

Add bfcl Repository to Gorilla Repository as a Submodule

Step 1: Clone the Gorilla Repository and Create a New Branch

git clone https://github.com/devanshamin/gorilla.git
git branch new_main
git checkout new_main

Step 2: Remove the Subfolder (berkeley-function-call-leaderboard) from the Gorilla Repository

git rm -r berkeley-function-call-leaderboard
git commit -m "Remove subfolder in preparation for submodule"

Step 3: Rewrite History to Remove Subfolder (berkeley-function-call-leaderboard) Commits

pip install git-filter-repo
git filter-repo --path berkeley-function-call-leaderboard --invert-paths --force
git remote add origin https://github.com/devanshamin/gorilla.git
git push -u origin new_main -f

Step 4: Add the New Repository (bfcl) as a Submodule

git submodule add https://github.com/devanshamin/bfcl.git berkeley-function-call-leaderboard
git add .gitmodules berkeley-function-call-leaderboard
git commit -m "Add `berkeley-function-call-leaderboard` as submodule"
git push origin new_main

Periodically Update the berkeley-function-call-leaderboard Submodule in the Gorilla Repository

Step 1: Update the Submodule to the Desired Release

cd berkeley-function-call-leaderboard
git checkout v0.1.0
cd ..

Step 2: Commit the Submodule Update

git add berkeley-function-call-leaderboard
git commit -m "Update submodule to v0.1.0"
git push origin new_main

[devanshamin]

Please share your thoughts - @ShishirPatil @CharlieJCJ @HuanzhiMao @Fanjia-Yan

• This way you guys can continue to resolve current issues with v0.1.* (patch releases) and I can work on the major release v1.0.0 on a separate branch.
• A user can always specify the version to run the BFCL.

GitHub releases provide a structured way to deliver software updates to users, making it easier for developers to manage and communicate changes effectively. For example,

• https://github.com/stanfordnlp/dspy/releases
• https://github.com/skypilot-org/skypilot/releases

[ShishirPatil]

At the onset thank you very much for the detailed write-up @devanshamin I am wondering if this is the best way forward. Would it be useful if I create a new-branch into which you can merge? And you can cherry-pick the git commits from main that are immediately relevant. We have adopted a policy of having just 2 branches, but this is one of the unique cases which warrants having a v0.1.0 branch instead of a separate submodule? Thoughts?

[devanshamin]

Yes, we can take that approach as well. As long as we have a copy of the main branch in a separate branch that one could always refer to, we can update the main branch with the refactored code. If the refactored code provides similar model responses and leaderboard scores,

• You can run git subtree split -P berkeley-function-call-leaderboard -b bfcl_main to create a branch bfcl_main containing the current berkeley-function-call-leaderboard code. For example: https://github.com/devanshamin/gorilla/tree/bfcl_main.
• Then we can merge the refactor_bfcl branch with the main branch.

This way, we ensure backward compatibility by having bfcl_main contain the original code and main with the up-to-date refactored code. I'm calling the branch bfcl_main, but you can give it a better name.