Using RBTools With Cliosoft SOS¶
This guide covers how you can use RBTools to post changes to Cliosoft SOS 7.20 or higher. We’ll cover posting both selections and changelists (new in SOS 7.20) for review.
A typical workflow looks like this:
We’ll follow go over these concepts and then show you an example session.
You’ll need to wait to commit your changes until after you’re finished with the review process and your change has been approved (with a Ship It!).
Changes that are already committed cannot currently be posted for review.
Step 1. Create a SOS changelist for your changes¶
SOS changelists are new in SOS 7.20, and are recommended to help you keep track of all the files that you want to post for review and, later, commit to your project.
Changelists require a writable workarea (soscmd newworkarea -LWRITABLE ...).
Changelists are created through socmd add, like so:
$ soscmd add -c <changelist_name> <file1> <file2> ...
$ soscmd add -c memory-leak-fix src/driver-main.c src/memutils.c
You can name the changelist anything you want, and can pass any files you’ve created, modified, or deleted.
If you choose not to use changelists, then you’ll instead post selections for review, which we’ll show below.
Step 2: Post your change for review¶
There are three ways you can post changes for review:
If you have a changelist to post, you can pass the name to
$ rbt post <changelist_name> Review request #123 posted. https://reviewboard.example.com/r/123/ https://reviewboard.example.com/r/123/diff/
$ rbt post memory-leak-fix
You can simply post all the files that you’ve modified or added to/deleted from checked-out directories by running:
$ rbt post Review request #123 posted. https://reviewboard.example.com/r/123/ https://reviewboard.example.com/r/123/diff/
That’s roughly equivalent to posting a selection represented by the
You can post an explicit selection:
$ rbt post "select:<flags>"
$ rbt post "select:-scm -sor -sunm" Review request #123 posted. https://reviewboard.example.com/r/123/ https://reviewboard.example.com/r/123/diff/
You can also provide the explicit files you want to post for review with
rbt post -I:
$ rbt post -I <file1> -I <file2>
Or exclude certain file patterns from a changelist or selection with
rbt post -X:
$ rbt post -X '*.txt'
These can be paired with a selection or a changelist name.
Once you’ve posted…¶
Your changes are now posted to Review Board, but are in a draft state. Nobody can see it until you’re ready to publish.
You’ll now need to go to the URL and fill out the Summary, Description, or any other fields.
If you have default reviewers set up, they’ll be assigned automatically, but you can also specify the people or groups you want to review your change.
Once you’re done filling out fields on the review request, click Publish to send it out for review.
Step 3: Update from reviewer feedback and re-post¶
Got some reviewer feedback to incorporate into your change? Easy.
Make the changes to your tree (make sure not to commit yet!)
If you’re using changelists, run
rbt post -u <changelist_name>to update your review request.
This will try to locate the review request you posted to before, comparing workarea ID and changelist name. It will ask you if it’s not sure which one is correct.
$ rbt post -u memory-leak-fix Review request #123 posted. https://reviewboard.example.com/r/123/ https://reviewboard.example.com/r/123/diff/
If you’re using selections, you’ll need to instead run
rbt post -r <review_request_id>with your preferred selection or
-Xto update the desired review request.
$ rbt post -r 123 Review request #123 posted. https://reviewboard.example.com/r/123/ https://reviewboard.example.com/r/123/diff/
$ rbt post -r 123 "select:-scm -sor -sunm" Review request #123 posted. https://reviewboard.example.com/r/123/ https://reviewboard.example.com/r/123/diff/
Update any information on the review request, if you want to.
We recommend describing the changes you’ve made, so reviewers know what to look for. The field for this is on the green draft banner.
Publish the new changes for review.
Rinse and repeat until you have the necessary approval to commit your change.
Step 4: Commit your change¶
Once you’ve gotten approval to commit the change, you can commit it using soscmd as normal.
To commit your changelist, use soscmd commit. For example:
$ soscmd commit -c memory-leak-fix
To commit your selections, use soscmd ci as normal.
Step 5: Close your review request¶
Now that your change is in, it’s time to close your review request.
Navigate to the review request and click Close -> Submitted.
Run rbt close <review request ID> (see the documentation).
Putting It All Together¶
Let’s walk through an example using changelists in a writeable workarea.
Posting Your Change¶
First, assume we’ve created a file (
newfile), deleted a file
oldfile), and modified a file (
Let’s create a changelist and add these files to it (note that we can call soscmd add multiple times if we want to):
$ soscmd add -c my-changelist newfile oldfile changedfile
We now have a changelist called
my-changelist. Let’s post it for review.
$ rbt post my-changelist Review request #1001 posted. https://reviewboard.example.com/r/1001/ https://reviewboard.example.com/r/1001/diff/
The review request will be posted, and will start off blank. You can go to the URL now to fill out those fields, and then click Publish.
Wait and grab some coffee…
Update From Review Feedback¶
Hey, we got some review feedback. Let’s make some changes to those files in our changelist and then update our review request:
$ rbt post -u my-changelist Review request #1001 posted. https://reviewboard.example.com/r/1001/ https://reviewboard.example.com/r/1001/diff/
Go to the review request, describe what you’ve fixed to help our your fellow reviewers, and publish the new draft.
Commit The Change¶
Once you’ve gotten an approval (reviews with a “Ship It!” that match your department/company’s policies), you can commit your change and close the review request.
$ soscmd commit -c my-changelist $ rbt close -r 1001
(You can also close it in the review request page).
You’ll get the hang of this process in no time. Soon you’ll be well on your way to better code quality.