Launched: Comments, Adding Context to Your Actions

A key part of problem identification is knowing what changed in the system. For developers this is often accomplished with comments in code this is to remind your 'Future Self' why you made the choices that you did. As we have built LaunchDarkly we have tried to follow our own best practices around naming flags with good descriptions, assigning clear owners to flags that map to specific areas of responsibility, and adding comments in our code to provide reminders on what a given flag is for.

However, as more teams using LaunchDarkly have implemented feature flag driven development practices the platform has become a crucial part of their change management process. For anyone that has experience with change management there is an acknowledgement that context matters. Standard audit logging is great to know who changed what, when; but lacks the why. In small systems or on small teams this often falls in the category of tribal knowledge, but in large systems and large organizations 30 seconds on formally documenting changes can save hours or days in the troubleshooting process.

Today, we are happy to rollout the ability to add comments on updates to flags. Now team members can have the option to add a brief comment on why a change is being made.

As we designed this feature we also thought it would be helpful to include these comments in your favorite established output path. So, when you do decide to add a little extra context folks will see it appear along with the who, what , and when sent to the audit log, through your established webhooks, slack channels, and Hipchat rooms.

If it's for a developer, build it on top of an API

In keeping with our mantra around API-first development the new comments functionality is built on top of the REST API.  We added the ability to submit these optional comments with PATCH changes. With this launch, the Update feature flag resource supports comments, and support in other PATCH resources is forthcoming.

Here's an example from our API docs for submitting a comment along with a JSON Patch document:

JSON

{  ""comment"": ""This is a comment string"",  ""patch"": [ {""op"": ""replace"", ""path"": ""/description"", ""value"": ""The new description"" } ]}

Oh, and one more thing

While we're strong proponents of JSON Patch as a protocol for describing partial updates in our REST API, we've found that it can be pretty verbose for simple changes. We've added support for the JSON Merge Patch protocol to address this. Here's an example merge patch document  that changes a feature flag's description:

JSON

{  ""description"": ""New flag description""}

Compare that to the equivalent JSON Patch document:

JSON

{  ""name"": ""New recommendations engine"",  ""key"": ""engine.enable"",  ""description"": ""This is the description"",  ...}

This addition also means that you can get fancy and combine these two new features and submit a comment along with a merge patch document:JSON{  ""comment"": ""This is a comment string"",  ""merge"": { ""description"": ""New flag description""}} Achievement unlocked. And now you'll know why.