V2 to V3 Guide

This guide will walk you through upgrading your Sourcebot deployment from v2 to v3.

Please note that the following features are no longer supported in v3:

• Local file indexing
• Raw remote .git repo indexing (i.e. not through a supported code host)

If your deployment is dependent on these features, please reach out.

This migration will require you to reindex all your repos

1. Spin down deployment
2. Delete Sourcebot cache (.sourcebot directory)
3. Migrate your configuration file to the v3 schema

   The main change between the v3 and v2 schemas is how the data is structured. In v2, you defined a repos array which contained unnamed config objects:

   {
       "$schema": "./schemas/v2/index.json",
       "repos": [
           {
               "type": "github",
               "repos": [
                   "sourcebot-dev/sourcebot"
               ]
           },
           {
               "type": "gitlab":
               "groups": [
                   "wireshark"
               ]
           }
       ]
   }
   

   In v3, you define a connections map which contains named connection objects:

   {
       "$schema": "./schemas/v3/index.json",
       "connections": {
           "sourcebot-connection": {
               "type": "github",
               "repos": [
                   "sourcebot-dev/sourcebot"
               ]
           },
           "wireshark-connection": {
               "type": "gitlab":
               "groups": [
                   "wireshark
               ]
           }
       }
   }
   

   The schema of the connections defined here is the same as the “repos” you defined in the v2 schema. Some helpful notes:

   • The name of the connection (sourcebot-connection and wireshark-connection above) is only used to identify the connection in Sourcebot. It can be any string that contains letters, digits, hyphens, or underscores
   • A connection is associated with one and only one code host platform, and this must be specified in the connections type field
   • Make sure you update the $schema field to point to the v3 schema
   • The settings object doesn’t need to be changed. We’ve added new settings params (check out the v3 schema for more details)
4. Start your Sourcebot deployment

   When you start up your Sourcebot deployment, it will create a fresh cache and begin indexing against your new v3 configuration file.

   If there are issues with your configuration file it will provide an error in the console. After updating your configuration file, restart your Sourcebot deployment to pick up the new changes.

5. You're done!

   Congrats, you’ve successfully migrated to v3! Please let us know what you think of the new features by reaching out on our discord or on GitHub.

Troubleshooting

Some things to check:

• Make sure you update the $schema field in the configuration file to point to the v3 schema
• Make sure you have a name for each connection, and that the name only contains letters, digits, hyphens, or underscores
• Make sure each connection has a type field with a valid value (gitlab, github, gitea, gerrit)

Having troubles migrating from v2 to v3? Reach out to us on discord or GitHub and we’ll try our best to help