Add support for artifact branches

[jsenko]

Notes and highlights:

• I've introduced new wrapper types for group, artifact, version and branch identifiers. I believe it makes the code more clear when a more specific type is used in the method parameter list instead of a bunch of String parameters. It also centralizes default group handling and validation. We can start using it gradually.
• Users can use branch name instead of a specific version in any REST calls where a version must be specified. I named that versionExpression to differentiate between cases where user has to specify plain version directly. This replaces the special keyword latest that we have currently. Users can use the latest branch, that is always available, by specifying .../branch=latest/....
• As a result of supporting version expressions, I was considering restricting the format of group, artifact, version and branch identifiers, but I'm not 100% sure about this yet. It would require handling during migration process to v3.
• I've disabled some migration tests, because they import v2 migration files which do not support branches. I've been working on a migration tool that would convert these to v3 migration files, and can run before the tests, but this will happen in a separate PR.
• I also plan to introduce a use-case for branches in a next PR - automated creation of branches based on semantic versioning.

[EricWittmann]

Why restrict groupId and artifactId to use [a-zA-Z0-9._-]{1,512} ? I can see why we'd want to do that for Version, but for the other two it doesn't seem necessary and just introduces a new limitation to 3.0 that we didn't have before, with no clear benefit that I'm seeing.

[jsenko]

Why restrict groupId and artifactId to use [a-zA-Z0-9._-]{1,512} ? I can see why we'd want to do that for Version, but for the other two it doesn't seem necessary and just introduces a new limitation to 3.0 that we didn't have before, with no clear benefit that I'm seeing.

yeah, I wasn't convinced of this myself, just that now would be a good opportunity to do it, in case we do something similar as with version. The length should remain restricted though, based on the database column size.

[EricWittmann]

Agree on the length restriction, as that always existed but wasn't documented in the openapi. But I don't think restricting the characters for those two fields makes sense unless we can find a reason for it.

[jsenko]

got it, I'll update it.

[EricWittmann]

Can you explain in this PR, at a high level, how the branches API is designed to work? Or how a user is expected to use branches in the "manual" use-case? I can see how this would work in the case of automatic branches (latest + semantic versioning).

Looking at the openapi, it looks like I can do the following:

1. List all the branches for an artifact
2. List all versions on a branch of an artifact
3. Delete a branch - deletes all versions in the branch??
4. Add (existing?) version to branch

Is this right? If yes, what's the flow for manual curation of a branch? I assume:

1. Create a new artifact with version 1.0
2. Create a new branch called 1.x
3. Add existing 1.0 version to branch 1.x
4. Create a new version 1.1
5. Add existing 1.1 version to branch 1.x

I suppose I could add the same version to multiple branches as well, right?

There isn't an explicit Create Branch I don't think? Maybe there should be one?

What about automatic branch creation for semantic versioning? Will I be able to delete those branches? Can I change the versions available on them?

Can I remove a version from a branch if I added it by mistake?

[EricWittmann]

Can I add a version to a branch during version creation? That would be interesting.

[EricWittmann]

Do you have new tests for the branch API? This is a big PR but I looked and didn't see anything.

[jsenko]

Do you have new tests for the branch API? This is a big PR but I looked and didn't see anything.

I think only on the storage level. I'll add one on the REST layer.

[jsenko]

Can I add a version to a branch during version creation? That would be interesting.

Good idea, will try to implement this.

[jsenko]

So, I've added the following changes based on the review:

• Remove format restrictions on group ID and artifact ID
• REST API level tests
• More consistent naming
• Improve UX by adding the following features:
  • Support creating a version and adding it to a branch (or multiple branches) in the same operation
  • Support a dedicated "rebase"-type operation, whereby the user can replace the branch with a different sequence of versions. This allows users to edit full branch history.
• Some small bug fixes

Can you explain in this PR, at a high level, how the branches API is designed to work?

Branches represent a sequence of versions. Currently, the main use-case is that they can be referenced in endpoints where a version name is expected. Instead of specifying a version directly, users can provide a version expression, e.g. branch=latest or branch=1.1.x, and the version on the tip of that branch is used for the given operation. There is a special branch named latest, which replaces the bespoke code we have used to support referencing the latest version. This branch is protected from updates and deletions, because it is intended for use in other features, replacing the versionOrder column we have at the moment. There are multiple operations for users to manage branches, with the following constraints:

• Branch cannot reference a non-existing version. When a version is deleted, it is removed from all branches. Vice-versa, if no branch references a version, it is also deleted. Effectively, however, since the latest branch always contains all versions (curretly at least) this does not happen (but is implemented).
• Branch may reference the same version multiple times.

Or how a user is expected to use branches in the "manual" use-case? I can see how this would work in the case of automatic branches (latest + semantic versioning)

Semantic versioning is the main use-case at the moment. The GroupsResourceTest provides a good showcase for available operations. Most common, I assume, will be the new feature, where users can specify the branch when creating a new version.

I suppose I could add the same version to multiple branches as well, right?

Correct!

There isn't an explicit Create Branch I don't think? Maybe there should be one?

I went with the create or update-style design, where a branch is created automatically as soon the first version is added to it. I think it fits the lightweight nature of branches, since they currently don't have a dedicated table for metadata. This can change in the future of course, e.g. if we need to track branch author, properties etc.

What about automatic branch creation for semantic versioning? Will I be able to delete those branches? Can I change the versions available on them?

yes, the plan is that they will work as any other branch, the only difference is that versions will be added to them automatically, based on content or provided metadata.

Can I remove a version from a branch if I added it by mistake?

yes, using the "rebase" (create or replace) operation.