If you have ever created or used an Actor, you may have noticed that Actors have builds. A build is basically a particular snapshot of the Actor stored on the Apify cloud. More specifically, each build is a Docker image that is used to start the container (Actor run). Fortunately, Apify hides this implementation detail from you so you don't need to understand Docker, images and containers at all. You can find more details about that in our docs.

Builds have this very cool feature that even if you have just created a new build of your Actor, you can choose to run any of your historical builds. This gives you the freedom to experiment with code or dependencies, since you know the older builds will keep working without being affected. You can also fork and tag your builds so that you create more distinct versions, such as beta or latest .

But if you want to publish your Actor, things get a little more complicated. When you're the only user of your Actor, you have full control over releasing new versions and keeping your integrations working. But a user of any public Actor is completely in the hands of the Actor creator. He or she can release breaking changes at any time and break your integration. Yes, you can technically fix the complete build version of the Actor you want to use (e.g. to 0.0.15),  but then you lose the ability to benefit from any improvements.

In this article, we will present best practices for you as an Actor publisher so that your users can benefit from your Actor updates but still be safe.

The default way of building Actors is simply to increment the latest  tag as your last build. If you build your Actor for the first time, the build will have the number 0.0.1  and the tag latest. If you build it again, the new number will be 0.0.2  and the latest  tag will move to this new build. You can see all builds with their tags in the Builds tab.

Any user that wants to run this Actor will use the build with latest  tag. 

When to use no-versioning?

For any other use case, we would highly recommend that you use versioning for your published Actors. Users will see that as a sign of stability and long-term vision.

The first rule of our versioning practice is to never use the latest tag. Since every build can have only one tag, we want this tag to describe a particular version.

Before you do your first build, go to the Source tab of your Actor and re-tag your current version. We will use notation version-0-0  for builds starting with 0.0  but you can choose your own tagging system, e.g. a simple increment like version-1 , version-2 ... 

Then you also need to update the default version new users will use. This will usually be the newest version. For now, we only have version-0-0 . Go to the Settings tab and update it.

Non-breaking changes are those that do not change the public interface (input/output) or the functionality of the Actor - usually bug fixes, performance improvements or changes of an underlying technology. 

For those changes, you can simply keep building the Actor with the same version tag, simply incrementing the last build number automatically, such as 0.0.2, 0.0.3, etc.

Don't forget to include these changes in your change log to keep your users informed.

If you want to publish a version that changes the public interface or the overall functionality, you should give it a different tag. This will help all current users keep their working integrations and all your new users can start with the new version right away.

Go to the Source tab and click on fork. Choose version 0.1 .
​

Now you can build the Actor. Don't forget to then tag this version as version-0-1  and change the default version (tag) in Settings. You should also update the change-log in your README.md so that your users know what changes each version brings.

Once your Actor reaches long-term stability, you can release a version 1.0 . Then for any big change in the Actor, you should update the major part of the version number, e.g. 2.0 , 3.0 , etc.

Automatic notification about new version
​Note that this notification has not yet been implemented. 

If you publish a new version of your Actor, all users of your Actor will be notified about this. They can then choose if they want to upgrade. All new users will start with the version that is defined in the Settings -> Default run options.

Some of you may have already published an Actor and would like to start the versioning practice presented above. It doesn't matter if you used only latest  tag or some other system. You just need to fork your current version, tag it and start using the new system. It doesn't matter that much whether you start with 0.0 , 0.1 or 1.0 . If you previously used the default latest  tag, it might become a bit confusing if you still have this tag for an older version, but from now on it should be clear that the versions keep incrementing.