API changes from 5.x-1.x to 5.x-2.x

New functions

• versioncontrol_get_operations() - solves all your problems and brews your tea.
• versioncontrol_get_operation_items() - now unified and centralized in the API module.
• versioncontrol_fetch_source_items() - find out where a set of items came from.
• versioncontrol_fetch_successor_items() - find out where a set of items ended up.
• versioncontrol_fetch_item_commit_operations() - find out to which commits some items belong.
• versioncontrol_has_write_access() - unified commit, branch and tag access check function.
• versioncontrol_insert_operation() - unified commit, branch and tag insertion function.
• versioncontrol_get_common_directory_path() - as replacement for the removed 'directory' element in operation arrays.
• versioncontrol_is_file_item(), versioncontrol_is_directory_item() and versioncontrol_is_deleted_item(), due to the increased usage of VERSIONCONTROL_ITEM_*_DELETED.
• versioncontrol_get_item() for retrieving items out of nothing, i.e. without any relationship to an existing item. Comes in handy for repository browsers.
• versioncontrol_get_item_selected_label() - retrieves the current branch or tag of an item and replaces versioncontrol_get_current_item_branch() and versioncontrol_get_current_item_tag(), as mentioned in the next section.
• versioncontrol_get_parallel_items() - retrieves related items on different branches and/or tags, and replaces versioncontrol_get_all_item_branches() and versioncontrol_get_all_item_tags().
• versioncontrol_fetch_item_revision_id() - adds the 'item_revision_id' identifier to an item if it exists in the database.
• versioncontrol_preg_item_match() - preg_match() replacement for item paths (shared between Commit Restrictions and workflow-ng integration).
• Extension modules can now implement hook_versioncontrol_alter_operation_constraints() to add custom operation constraints. Interim measure until issue #216373 is fixed (and already a step in the right direction, although I'm just noticing that the "alter" in the function name should probably be a suffix to the rest of the name).

Removed/renamed functions

• Renamed versioncontrol_get_commits() to versioncontrol_get_commit_operations(), in order to bring it in line with the versioncontrol_get_branch_operations() and versioncontrol_get_tag_operations() naming scheme. (Which is fine because all of those are actually contained in the same data structure.)
• Removed versioncontrol_get_commit_actions(), versioncontrol_get_branched_items() and versioncontrol_get_tagged_items(), in favor of versioncontrol_get_operation_items(). (Likewise, all occurrences of $commit_actions need to be reworked as $operation_items.)
• Removed versioncontrol_get_commit_branches() in favor of $operation['labels'].
• Removed versioncontrol_get_directory_item(), as the 'directory' column isn't stored in the database anymore - see the "Changed semantics" section on 'directory' for more info on this.
• Removed versioncontrol_get_affected_item(), not necessary anymore because all operation items are "affected items".
• Removed versioncontrol_get_current_item_branch() and versioncontrol_get_current_item_tag() in favor of versioncontrol_get_item_selected_label().
• Removed versioncontrol_get_all_item_branches() and versioncontrol_get_all_item_tags() in favor of versioncontrol_get_parallel_items().
• Removed versioncontrol_get_commit_statistics() in favor of the $item['line_changes'] array (see versioncontrol_get_operation_items() API documentation for more information).
• Removed versioncontrol_has_commit_access(), versioncontrol_has_branch_access() and versioncontrol_has_tag_access() in favor of versioncontrol_has_write_access(). New mandatory elements: 'label', 'type'.
• Removed versioncontrol_insert_commit(), versioncontrol_insert_branch_operation() and versioncontrol_insert_tag_operation() in favor of versioncontrol_insert_operation().
• Removed versioncontrol_get_branch(), versioncontrol_get_branch_id() and versioncontrol_ensure_branch(), this stuff is now private to the API and should only be accessed via the 'labels' property. If you need to mess around with existing labels (yeah, I mean you, Git backend) then please do so by direct database access or come up with a set of functions to update operation related stuff. [Edit: in 6.x-1.x, versioncontrol_ensure_label() has been (re-)introduced, which makes for a proper replacement. Other issues made it necessary to expose it, too, so we might not get away without such a function. In the meantime, you probably can use _versioncontrol_ensure_label() in the 5.x-2.x branch, even though it's private. That's an exception, though.]
• Removed versioncontrol_get_file_contents() in favor of versioncontrol_get_file_copy().
• Renamed versioncontrol_format_commit_identifier() to versioncontrol_format_revision_identifier(). Backends can implement [versioncontrol_backend]_format_revision_identifier() in order to display revision identifiers in a custom fashion. Unfortunately, jpetso forgot to adapt versioncontrol_format_item_revision() so you need to have both the [versioncontrol_backend]_format_revision_identifier() and [versioncontrol_backend]_format_short_revision_identifier() functions if you want all revision identifiers to be formatted. That API issue will only be resolved in 6.x-1.x.

Hook changes

• hook_versioncontrol_write_access() - replaces hook_versioncontrol_{commit,branch,tag}_access() (same for [versioncontrol_backend]_write_access()).
• hook_versioncontrol_operation() - replaces hook_versioncontrol_{commit,branch_operation,tag_operation}() (same for [versioncontrol_backend]_operation()).

Changed semantics

• Commit action arrays are gone, replaced by the unified item array format. (Look up the versioncontrol_get_operation_items() docs for that.) Mind that 'source_items' (and 'replaced_item') is now spelled with an underscore! 'source_items' (after calling versioncontrol_fetch_source_items(), at least) is now empty instead of not set.
• In many cases, it will be a good idea to use versioncontrol_get_operations() instead of versioncontrol_get_commit_operations(), versioncontrol_get_branch_operations() and versioncontrol_get_tag_operations().
• versioncontrol_get_branch_operations() and versioncontrol_get_tag_operations() now also return commits for version control systems that don't support branches and tags natively (that is, Subversion).
• The 'directory' element in operation arrays is gone. Use versioncontrol_get_common_directory_path() to calculate the directory on the fly - although passing the result of versioncontrol_get_operation_items() will not yield the same result, you have to also have to add the source items for retrieving the same directory that the 'directory' element contained before. If you need the directory as item, call versioncontrol_get_parent_item() on one of the items that you passed before.
• versioncontrol_get_item_history() is now implemented by the API module (made possible by the new table layout) so 1. it will work most times without the backends actually contributing their wisdom, and 2. it has two new limit parameters (how far to look into the past, and how far in the future, compared to the current item state) so you don't have to drain the database if you don't want to.
• versioncontrol_get_commit_statistics() has already changed function signature and result value, but should change a lot more still.
• versioncontrol_get_user_statistics() now queries on all operations. Also, the set of allowed $order parameters has changed (now 'by_date' and 'by_number') and the result value includes '*_operation' keys instead of '*_commit' ones.

Backend-only changes

• [versioncontrol_backend]_get_short_revision_identifier() has been renamed to [versioncontrol_backend]_get_revision_identifier(), and is now supposed to handle all possible formats if implemented. Therefore its function signature was also changed, see the FakeVCS backend for the new version.
• versioncontrol_get_parent_item() cannot be overridden by [versioncontrol_backend]_get_parent_item() anymore. The API module does a better job at this now, so with a little luck we can avoid an alter function in the future too.
• There's a new capability constant, VERSIONCONTROL_CAPABILITY_DIRECTORY_REVISIONS, which indicates that the VCS also tracks directory revisions. If this applies to your backend (SVN has been handled... other contenders?) then add this constant to your hook_versioncontrol_backends() implementation.
• Backends now need to implement [versioncontrol_backend]_get_selected_label_from_operation() and [versioncontrol_backend]_get_selected_label_from_other_item(), on the other hand they can drop their versioncontrol_get_current_item_{branch,tag}() implementations (and others for which no replacement is required) as mentioned in the "Removed/renamed functions" section.
• The VERSIONCONTROL_ITEM_*, VERSIONCONTROL_FILE_* and VERSIONCONTROL_ACTION_* constants have been increased by one so that the first constant for regular items, files or actions starts at 1. There's a new VERSIONCONTROL_ITEM_EMPTY for internal use, which is defined as 0 and will be used for storing actions in {versioncontrol_source_items} for which no actual source items exist. If your backend has these constants stored somewhere in the database, please increase them by 1 and only afterwards transfer to the new centralized item revision tables. (Theoretically this point would be outside of the backend section, but I'm not aware of any other module storing these constants.)

API changes in versioncontrol_project

• Renamed versioncontrol_project_get_projects_for_commit() to versioncontrol_project_get_projects_for_operation(), in order to reflect the extended scope of this function with broader applicability.
• versioncontrol_project_get_project_for_item() can now also be passed whole items, which in many cases yields a slight performance win as it can distinguish between file and directory items (only the latter of which need to be queried in the database).