Tracking API changes per code branch


(Kmeister) #1

Is there a preferred workflow for multiple changes to an API which is in-development?

My example is:

  1. Developer A, is building feature A which needs its own tests.
  2. Developer B, is building feature B which needs its own tests.
  3. Each codebase A and B can be tested using the correct version.
  4. When the features are merged together, both sets of tests can be run.

Any ides on how to do this with stoplight would be most welcome.


(Marc) #2

Hi @kmeister, great question!

Short Answer

Short answer is that we are working towards a specific workflow, but not all of the pieces are in place to support it quite yet. For now, we would recommend creating a scenario collection file for each set of independent tests/feature, and then either merging them together when you are done, or simply triggering both collections when testing.

To merge them together, you can switch to code view and copy all of the scenarios in file A, then paste them in the code view of file B.

This is a temporary measure until we get the full versioning system in place.

Long Answer

Under the hood, projects in Stoplight are git repositories, and git serves as the foundation for the versioning workflow that we are working towards. We’re building a lightweight UI around git to help manage and merge multiple versions from within Stoplight (or, if you prefer, you can of course use whatever Git tooling you want to help manage the merging/branching etc).

In fact, you can already see indicators of the git underpinnings in our URLs (see master version below):

or in features like the change history (which pull data from the git commit history).

The UI we are building is not meant to be a full and complex git client, but rather a simpler set of features to help all personas (from product manager to technical writer to developer) collaborate around versions inside of Stoplight. However, because we’re on git, those with technical chops who want to drop down to lower level git operations can do so, while product managers etc use the lightweight Stoplight UI.

I hope this helps to answer your question, and provides some insight into where we’re headed! Let me know if anything isn’t clear or if you have other ideas or suggestions :slight_smile:.


(Nicolas Tisserand) #3

Hi @kmeister,

In addition to Marc’s answer, there is a first condition to be fulfilled before testing : the Swager must contains both of the features A and B.
This point is not always easy to deal with. For example :

  • if A is about “books” and B is about “users” with no link between them : no problem, the Swagger can be merged and you can follow Marc’s advice.
  • if A and B concerns “books”, and B needs to change the “books” models, then you are more likely talking about API versioning and it’s more difficult. Depending on the complexity level of your project, you’ll probably have to stage the deployment of your features, manage the migration of the consumers, and so on.

(Kmeister) #4

These are good points, @marc @ntiss

Our system is more like what Nicolas describes, which is what tracking scenario changes locally gives us. The tests move along with the API code of that feature release.

For 2 test scenario files Marc describes maybe what we need to do. We have had major conflicts with automatically merging the scenario file, but multiple separate files would be ideal.

If prisim did correctly support local shared utility methods we would be in a lot better position as each feature would be able to be in its own json. Right now we have a monolith scenarios json, its quite overwhelming if not for the Stoplight app.