Gem Transfers #5758

colby-swandale · 2025-06-23T13:23:09Z

This Pull Request is the last remaining feature needed to begin private beta testing of Organizations in rubygems.org! This Pull Request introduces a system for a Rubygem to transition from being owned by a set of Users to being owned by an Organization.

Gem transfers work very similarly to Organization Onboardings in that they take a user through a multi-step process that asks for information like:

What Organization will the gem move to
What roles should be assigned to each of the gem owners?
Asking the User to confirm everything entered and perform the migration

Breaking Change: OrganizationOnboardingInvite

Back in #5201, I introduced a table/model called OrganizationOnboardingInvite, which captured the User and associated role for the Organization Onboarding system. This model works great, and I've reused the same functionality here.

To reduce duplication, I'm deprecating and deleting (the empty) the OrganizationOnboardingInvite model and moving everything to OrganizationInduction that will work for both Organization Onboardings & Gem Transfers.

Screenshots

User Management

Select an Organization

Gem Transfer Button/Link

Confirmation Screen

codecov · 2025-06-23T13:32:39Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.18%. Comparing base (5979c67) to head (296edf0).
Report is 11 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5758      +/-   ##
==========================================
+ Coverage   97.15%   97.18%   +0.03%     
==========================================
  Files         460      469       +9     
  Lines        9559     9676     +117     
==========================================
+ Hits         9287     9404     +117     
  Misses        272      272

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

landongrindheim

Leaving comments which I'll return to as I continue this review.

app/avo/resources/organization_induction.rb

app/controllers/rubygems/transfer/confirm_controller.rb

app/controllers/rubygems/transfer_controller.rb

app/controllers/rubygems/transfer/users_controller.rb

landongrindheim · 2025-06-23T19:07:27Z

db/migrate/20250618055332_create_rubygem_transfers.rb

+      t.string :status, null: false, default: "pending"
+      t.references :organization, null: true, foreign_key: { to_table: :organizations }
+      t.references :created_by, null: false, foreign_key: { to_table: :users }
+      t.references :rubygem, null: false, foreign_key: { to_table: :rubygems }


🤔 My understanding of a transfer is that it's updating ownership from one entity to another. In that model, I might be using a from_organization and a to_organization. This data could be used for auditing. What do you think of capturing this information? Does it fit our needs?

landongrindheim · 2025-06-23T20:05:10Z

app/views/organizations/onboarding/confirm/edit.html.erb

+<% @title = "Create an Organization" %>
+


🔎 There are a few instances of @title being set in views. What do you think of moving assignment to the controller?

landongrindheim · 2025-06-23T20:07:58Z

app/models/rubygem_transfer.rb

+    self.invites = users_for_rubygem.map { |user| existing_invites[user.id] || OrganizationInduction.new(user: user) }
+  end
+
+  def rubygem_ownership


💅 What do you think of #authorized_to_give??

The purpose of the rubygem_ownership is a bit different from what you would expect a predicate method to do. Maybe we can move the policy check into it's own method, but that feels unnecessary right now?

landongrindheim · 2025-06-23T20:19:30Z

app/models/rubygem_transfer.rb

+    errors.add(:rubygem, "does not have permission to transfer this gem")
+  end
+
+  def organization_ownership


💅 What do you think of #authorized_to_receive??

Same thought as above

app/models/organization_onboarding.rb

landongrindheim

I've been thinking about this a bunch and wanted to propose a model which I think might cover the needs we have and extend beyond them nicely. There are still a couple of cases that would need to be ironed out, but I think they're within reach.

Ownership Model

A Rubygem is owned by a User OR an Organization
An Organization has many members (Users)
- These members have access based on their roles in the org
A Rubygem optionally has contributors (via Contributorships)
- contributors have a default set of permissions, though they could be extended
- The owner of the Rubygem would manage contributors

Assumptions

If a Rubygem is owned by a User, the user has all permissions (admin, owner, etc)
Permissions in an organization are dependent on the role within the organization
Permissions for contributors are limited and do not (?) overlap with organization membership permissions

Further work

If a contributor joins an organization:
- Leave contributorship as is? (cascade permissions, so we never have to worry about hitting this)
- Soft-delete contributorship?
If a member leaves an organization:
- Organization owner determines whether to retain contributorship

erDiagram
    User {
        int id
        string name
        string email
    }
    
    Organization {
        int id
        string name
        string description
    }
    
    Rubygem {
        int id
        string name
        string version
        int owner_id
        string owner_type
    }
    
    Membership {
        int user_id
        int organization_id
        string role
        datetime joined_at
    }
    
    Contributorship {
        int user_id
        int rubygem_id
        string permission_level
        datetime granted_at
    }
    
    %% Core ownership relationships
    User ||--o{ Rubygem : "owns (individual)"
    Organization ||--o{ Rubygem : "owns (organizational)"
    
    %% Organization structure
    User ||--o{ Membership : "belongs to"
    Organization ||--o{ Membership : "has members"
    
    %% Gem contributorships (outside contributors only)
    User ||--o{ Contributorship : "contributes to"
    Rubygem ||--o{ Contributorship : "has contributors"
    
    %% Notes on roles and permissions
    %% Membership.role: owner, admin, member
    %% Contributorship.permission_level: maintainer, contributor
    %% Rubygem.owner_type: User or Organization

app/views/rubygems/transfer/organizations/new.html.erb

app/models/rubygem_transfer.rb

app/views/rubygems/transfer/users/edit.html.erb

landongrindheim · 2025-06-24T15:42:44Z

app/models/rubygem_transfer.rb

+
+  before_save :sync_invites, if: :organization_changed?
+
+  def transfer!


🤔 I wonder about #finalize! or #complete! as a name here. Since the transfer process is multi-step, the name seems incomplete (and potentially redundant with RubygemTransfer being the class). What do you think?

transfer! to me communicates the intent of what this big method does well. You don't have to dive into the 50 lines of code to figure out what it's doing.

simi · 2025-06-30T20:16:12Z

@landongrindheim ad the Ownership Model, can't we make it simpler and make implicit organization per user so gem is always owned by organziation? This will make later planned changes like namespacing easier to introduce, since there will be only one way to own gem.

A Rubygem optionally has contributors (via Contributorships)

I don't think that's good name. Contributors is term used for users contributing to the codebase (like on GitHub) not related to release process. I think "maintainer" or "release manager" would be better name.

landongrindheim · 2025-06-30T20:31:51Z

@landongrindheim ad the Ownership Model, can't we make it simpler and make implicit organization per user so gem is always owned by organziation? This will make later planned changes like namespacing easier to introduce, since there will be only one way to own gem.

@simi This was my initial thought. Something like community could be a default organization, which could become the new home of ownerships. Migrating data will be necessary to achieve this, so it's inherently a non-trivial task.

A Rubygem optionally has contributors (via Contributorships)

I don't think that's good name. Contributors is term used for users contributing to the codebase (like on GitHub) not related to release process. I think "maintainer" or "release manager" would be better name.

I agree the name is lacking. My assumption is that organizations will typically map to businesses or similar, and that there will be a need for including someone who doesn't belong to the business and shouldn't have the ability to take actions for all the organization's resources. I'm trying to capture that role. Is that a good fit for "maintainer" or "release manager"? If not, do you know of another term?

simi · 2025-06-30T20:45:23Z

This was my initial thought. Something like community could be a default organization, which could become the new home of ownerships. Migrating data will be necessary to achieve this, so it's inherently a non-trivial task.

@landongrindheim I think we can just make implicit organization for everyone named same as profile name (handle). We can also make implicit organization per gem 🤔.

The original problem was related to fact, you were able to only add owner to gem and owner had all permission, so in theory the new owner was able to remove you as original owner and fully take over the gem. Usually gem owners were looking for someone to help (be able to release new versions) without risk of losing control over the gem. That's how Maintainer role was born (#4883).

The second problem was you need to do this gem by gem. Some projects do often maintain big amount of gems (like here, each folder is separate gem https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/75bab36aa8901b40bf2bc5017581302d581ed0ea/instrumentation) and it is hard to maintain permissions in bulk. That's what Organizations should fix.

And the final part is to ensure it all works together. In my thinking the organization is more like entity owning group of gems + their maintainers and owners under one umbrella. OpenTelemetry Ruby projects is hosting 2 kind of gems (per my understanding), core gems and contrib gems. I assume they will create 2 organizations for this on RubyGems.org to be able to add different maintainers per each type.

…e polymorphic association

Co-authored-by: Landon Grindheim <landon.grindheim@gmail.com>

…sInvite#principal to #invitable

This is primarily being done to keep us in compliance with CodeCov

This is primarily driven by getting CodeCov satisfied

landongrindheim

I added some tests to satisfy the CodeCov build. At the least I don't think they hurt. I think it's in a good place to move forward.

github-project-automation bot moved this to Todo in RubyGems.org Pull Requests Jun 23, 2025

github-project-automation bot added this to RubyGems.org Pull Requests Jun 23, 2025

landongrindheim reviewed Jun 23, 2025

View reviewed changes

landongrindheim reviewed Jun 30, 2025

View reviewed changes

colby-swandale marked this pull request as ready for review July 1, 2025 07:02

colby-swandale and others added 7 commits July 1, 2025 07:10

rename OrganizationOnboardingInvite to OrganizationInduction, and mak…

fa9f29f

…e polymorphic association

add rubygems transfer model

66e92b8

Add gem transfer controllers

e094c32

quality of life tweaks

e8f52aa

Update app/views/rubygems/transfer/organizations/new.html.erb

2ee31da

Co-authored-by: Landon Grindheim <landon.grindheim@gmail.com>

rename controllers

92d4057

Rename OrganizationInduction to OrganizationInvite and rename RubyGem…

48b3772

…sInvite#principal to #invitable

colby-swandale force-pushed the colby/gem-transfers branch from 4037311 to 48b3772 Compare July 1, 2025 07:13

colby-swandale and others added 7 commits July 1, 2025 08:06

Fixup errors from CI

9560bde

fix missing constant and fill locales

5a7b611

resolve breaking tests

7f2be4d

quality of life improvement and fixing tests

d2f6c47

Bolster test coverage

0e915ae

This is primarily being done to keep us in compliance with CodeCov

Add test case for transfer failures

2ea9081

Bolster test coverage

6d8ddce

This is primarily driven by getting CodeCov satisfied

landongrindheim approved these changes Jul 1, 2025

View reviewed changes

github-project-automation bot moved this from Todo to Ready in RubyGems.org Pull Requests Jul 1, 2025

colby-swandale added 2 commits July 3, 2025 01:34

Don't how transfer link unless the user is in an organization

8bd09fc

cleanup

296edf0

colby-swandale merged commit 23fa363 into master Jul 3, 2025
20 of 21 checks passed

colby-swandale deleted the colby/gem-transfers branch July 3, 2025 03:14

github-project-automation bot moved this from Ready to Merged in RubyGems.org Pull Requests Jul 3, 2025


		before_save :sync_invites, if: :organization_changed?

		def transfer!

Uh oh!

Gem Transfers #5758

Gem Transfers #5758

Uh oh!

Conversation

colby-swandale commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking Change: OrganizationOnboardingInvite

Screenshots

User Management

Select an Organization

Gem Transfer Button/Link

Confirmation Screen

Uh oh!

codecov bot commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

landongrindheim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

landongrindheim Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

landongrindheim Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

landongrindheim Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

colby-swandale Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

landongrindheim Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

colby-swandale Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

landongrindheim left a comment

Choose a reason for hiding this comment

Ownership Model

Assumptions

Further work

Uh oh!

Uh oh!

Uh oh!

Uh oh!

landongrindheim Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

colby-swandale Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simi commented Jun 30, 2025

Uh oh!

landongrindheim commented Jun 30, 2025

Uh oh!

simi commented Jun 30, 2025

Uh oh!

landongrindheim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

colby-swandale commented Jun 23, 2025 •

edited

Loading

codecov bot commented Jun 23, 2025 •

edited

Loading

colby-swandale Jul 1, 2025 •

edited

Loading

colby-swandale Jul 1, 2025 •

edited

Loading