docs: Describe RemoveRepository behaviour

While reading and trying to understand how the repository was removed on
both the Rails and Gitaly side, I found it confusing that the RPC wasn't
describing behaviour that the caller wants to know.

This change documents the internals of an RPC so hopefully it's clearer
what Gitaly provides to callers.

2 files changed, 9 insertions, 0 deletions

diff --git a/proto/go/gitalypb/repository-service.pb.go b/proto/go/gitalypb/repository-service.pb.go
index 00f18bfef..2aefd9ab9 100644
--- a/proto/go/gitalypb/repository-service.pb.go
+++ b/proto/go/gitalypb/repository-service.pb.go
@@ -4320,6 +4320,9 @@ type RepositoryServiceClient interface {
 	GetObjectDirectorySize(ctx context.Context, in *GetObjectDirectorySizeRequest, opts ...grpc.CallOption) (*GetObjectDirectorySizeResponse, error)
 	CloneFromPool(ctx context.Context, in *CloneFromPoolRequest, opts ...grpc.CallOption) (*CloneFromPoolResponse, error)
 	CloneFromPoolInternal(ctx context.Context, in *CloneFromPoolInternalRequest, opts ...grpc.CallOption) (*CloneFromPoolInternalResponse, error)
+	// RemoveRepository will move the repository to `+gitaly/tmp/<relative_path>_removed` and
+	// eventually remove it. This ensures that even on networked filesystems the
+	// data is actually removed even if there's someone still handling the data.
 	RemoveRepository(ctx context.Context, in *RemoveRepositoryRequest, opts ...grpc.CallOption) (*RemoveRepositoryResponse, error)
 	RenameRepository(ctx context.Context, in *RenameRepositoryRequest, opts ...grpc.CallOption) (*RenameRepositoryResponse, error)
 	ReplicateRepository(ctx context.Context, in *ReplicateRepositoryRequest, opts ...grpc.CallOption) (*ReplicateRepositoryResponse, error)
@@ -4990,6 +4993,9 @@ type RepositoryServiceServer interface {
 	GetObjectDirectorySize(context.Context, *GetObjectDirectorySizeRequest) (*GetObjectDirectorySizeResponse, error)
 	CloneFromPool(context.Context, *CloneFromPoolRequest) (*CloneFromPoolResponse, error)
 	CloneFromPoolInternal(context.Context, *CloneFromPoolInternalRequest) (*CloneFromPoolInternalResponse, error)
+	// RemoveRepository will move the repository to `+gitaly/tmp/<relative_path>_removed` and
+	// eventually remove it. This ensures that even on networked filesystems the
+	// data is actually removed even if there's someone still handling the data.
 	RemoveRepository(context.Context, *RemoveRepositoryRequest) (*RemoveRepositoryResponse, error)
 	RenameRepository(context.Context, *RenameRepositoryRequest) (*RenameRepositoryResponse, error)
 	ReplicateRepository(context.Context, *ReplicateRepositoryRequest) (*ReplicateRepositoryResponse, error)
diff --git a/proto/repository-service.proto b/proto/repository-service.proto
index 3f7b3f405..a3cad35c9 100644
--- a/proto/repository-service.proto
+++ b/proto/repository-service.proto
@@ -205,6 +205,9 @@ service RepositoryService {
       op: MUTATOR
     };
   }
+  // RemoveRepository will move the repository to `+gitaly/tmp/<relative_path>_removed` and
+  // eventually remove it. This ensures that even on networked filesystems the
+  // data is actually removed even if there's someone still handling the data.
   rpc RemoveRepository(RemoveRepositoryRequest) returns (RemoveRepositoryResponse) {
     option (op_type) = {
       op: MUTATOR