Version Control
In the absence of a formal version control system in Postman, users have developed a variety of methods to manage changes. Some work on duplicates of collections / requests, requiring a manual merge of these to maintain a single source of truth. Others rely on existing version control services, maintaining their source on Github etc. while using an integration to keep their requests in Postman up to date. However, as workflows get more complex, an inbuilt version control system can provide a more seamless way of working with changes.

An integrated version control system

There are existing version control systems that users can rely on to maintain different versions of their APIs. However, Postman’s ability to better interpret and predict the collection schema can offer a seamless collaborative experience while working with entities in Postman. We can then provide versioning and conflict resolution experiences which are much simpler, and more tailored to these entities, such as collections and environments.

A model for working with versions

Postman uses the sync service to maintain all versions of an entity , allowing for a single source of truth for users collaborating on them. These versions are maintained as a series of revisions (or changes), allowing further features to be built on top of this, such as a review process, forking and tagging

Terminology

While such a version control system can technically be extended to all JSON entities in Postman (environments, mocks etc.), for the purpose of this RFC, we shall restrict our scope to versioning collections.
Version
The state of a collection at a given point in time. Versions are identified by the revisions made on a collection.
Revision
A set of changes made to a collection. 
Tag
A label or pointer to a specific version of a collection. Tags can be added to any version of a collection.
Fork
A copy of a collection with a reference to the original collection. Forks will have their own versions, revisions, access control and entities attached to them. This will allow for forks of collections to have their own monitors, mocks etc.  
Merge
An action performed on a collection to combine it's contents with that of a destination collection. Forks can be merged back into their original collections.
Merge Request
A request sent to an author of a collection to accept a series of revisions and merge a fork back into the original collection.
Conflict
A situation that occurs when a merge cannot be completed automatically because the original has changed since the fork was created.

Common Workflows

Tagging a version of a collection
A user can select a particular point in the activity feed of a collection to add a tag to that version. While tags in this form are just used as a visual reference to a version, this can be later extended for use in referencing the collection. For example, a monitor could be added on a specific tagged version of a collection. If tags could be moved around to point to different versions, a set of monitors or mocks can always point to the tag, so the actual collection underneath could change later.


Forking a collection
Forking a collection creates a new collection with a reference to the original collection. This reference is maintained to be able to easily diff between the two entities. A forked collection is a separate collection with its own activity and permissions. Teams have the flexibility of building their own workflows around forking collections. Forked collections can be used as copies for individuals or sub-teams to work in silos OR as a way to separate concerns within a team. A user can fork any collection that they have read access to.


Merging contents of collections
A merge action is used to integrate changes of a source collection with that of a destination collection. The result of a merge is applied on the destination collection only. By definition, a merge action will not delete the source collection. 

While a merge action can theoretically be performed on ANY two collections, not just forked collections, merges between forked collections will show more reliable diffs, since each attribute of an entity has a reference in the other entity. For example, a request reordering diff between forked collections can be accurately identified as reordered. The same diff between two arbitrary collections however would show as a completely new set of requests.

Since merge actions affect the contents of the destination collection, their process is governed by the access control on the destination collection.
  1. All users with read access on a collection can initiate a merge. However, only users with write access can approve a merge.
  1. While performing a merge action, the user can request another user with write access to review and approve the merge.
  1. If a user themselves have write access to a destination collection, they can perform the merge without any approval.

Merge requests can be shown as list views on their respective entities and workspaces.


Reviewing a merge
Any user with write access to the collection can review and complete the merge. The reviewer selects the changes that they approve of, and merge those into the destination collection. A merge action on completion will then appear as an revision action on the activity feed. The review process itself can be made more collaborative by adding comments and multiple reviewers in the future.  


Conflicts
When attempting to merge a forked collection, a conflict may arise if the same attributes have been modified in both the source and destination. In this case, a warning modal is thrown while attempting the merge and the user can choose to resolve conflicts inline before sending the merge request. Conflict resolution involves merging changes made to the parent collection back to the modified forked collection. Before a merge request is approved, all conflicts must be resolved by anyone who has write access to the source collection.