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:

Create a SOS changelist for your changes (optional)
Post your changes for review (via changelist or selection)
Make changes based on feedback and re-post for review
Commit your change to SOS
Close your review request

We’ll follow go over these concepts and then show you an example session.

Important

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.

Note

Changelists require a writable workarea (soscmd newworkarea -LWRITABLE ...).

Changelists are created through socmd add, like so:

$ soscmd add -c <changelist_name> <file1> <file2> ...

For example:

$ 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 post.

$ rbt post <changelist_name>
Review request #123 posted.

https://reviewboard.example.com/r/123/
https://reviewboard.example.com/r/123/diff/

For example:

$ 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 -scm selection flag.

You can post an explicit selection:

$ rbt post "select:<flags>"

For example:

$ rbt post "select:-scm -sor -sunm"
Review request #123 posted.

https://reviewboard.example.com/r/123/
https://reviewboard.example.com/r/123/diff/

Including/Excluding Files¶

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.

For example:

$ 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 -I/-X to update the desired review request.

For example:

$ rbt post -r 123
Review request #123 posted.

https://reviewboard.example.com/r/123/
https://reviewboard.example.com/r/123/diff/

Or:

$ 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 (changedfile).

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.

Tip

You can update (-u), describe the changes (-m), and publish (-p), all in the same step:

$ rbt post -u -m "Fixed a broken link." -p my-changelist

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.