Design doc for organizations #5958

stsewd · 2019-07-18T20:11:16Z

These are some considerations to make before having organizations. Most of the problems are because we already have organizations in the corporate site.

There are some decisions to make. I think the biggest ones are how to support organizations and namespacing.

For how to support organizations, I think number 2 (support users and organizations to own projects) is the way to go.

ericholscher

This is a good initial step. We should update it so it reflects our decisions on the questions it asks, and start actually doing the work.

docs/development/design/organizations.rst

ericholscher · 2019-08-26T21:01:59Z

docs/development/design/organizations.rst

+So, we should only support admin permissions for teams.
+
+Subscriptions, this is only valid for the corporate site,
+since we don't charge for use in the community site.


We could have our Gold users map onto this, but I don't think it should be part of this migration.

ericholscher · 2019-08-26T21:03:12Z

docs/development/design/organizations.rst

+
+We could keep the current behavior for the community site and use `organization.slug` + `project.slug` for the corporate site,
+since in the corporate site we don't care so much about a unique namespace between all users, but a unique namespace per organization.
+We can refactor the way we get the namespace to be more easy to manage in both sites.


Yea, I think we will need to keep both namespaces, since we don't want to break existing URL's. It should be simple enough to support by just changing the logic around slug creation.

davidfischer

I made a few small notes for clarity but I'm on board with this change. I think organizations will be great on the community site.

docs/development/design/organizations.rst

humitos

The document looks good to me. I left some comments to clarify some sentences, but I'm mostly 👍 with it.

docs/development/design/organizations.rst

humitos · 2019-10-04T15:30:32Z

docs/development/design/organizations.rst

+- Subscription
+
+This app can be named *subscriptions*.
+We can get around the table names and migrations by setting the explicitly the table name to `organizations_<model>`,


I think it's not terrible to rename a table, and will be cleaner. If it's trivial, I'd say that we should do it.

That would generate some downtime.

I think we can clean it up later. It doesn't need to be done now.

humitos · 2019-10-04T15:34:28Z

docs/development/design/organizations.rst

+In the community site we run an initial migration,
+for the corporate site we run a fake migration.


How are we going to have different migrations files for the same organizations app if it will be same code base?

The models are already created on the commercial site, we can't run the migrations there again. We can remove the old migration files on the commercial site after the migration.

Why not just run the migrations on the community site without removing any migration file? When all these migrations are ran in the corporate site as well, they will do nothing.

The app is different and the migration files from .com depend on other models and migrations that aren't on .org.

I think the plan is to just squash the migrations and start with the current state as initial. This makes sense to me, as nobody will be needing to catch up to the current state, and it's effectively a new app in the .org.

docs/development/design/organizations.rst

Co-Authored-By: David Fischer <djfische@gmail.com>

humitos · 2019-10-10T11:54:14Z

Another thing that I want to mention here is that in Corporate we have a Organization.projects field which is a ManyToManyField to Project. Although, we do not support this relationship: a Project can not be part of two organizations.

Do we plan to support that? In that case, will it add any value from a user perspective?

In case we don't, we should make it a ForeignKey on Project instead and remove all the code that we have like project.organizations.first() to get the organization of the project --will make things simpler and clearer.

stsewd · 2019-10-10T15:25:02Z

In case we don't, we should make it a ForeignKey on Project instead and remove all the code that we have like project.organizations.first() to get the organization of the project --will make things simpler and clearer.

I'm +1 on that, can be done before moving the code.

ericholscher

I think this is mostly ready to merge and start on. It's definitely not solving some of the problems that we'll hit along the way, but I think this plan makes sense.

docs/development/design/organizations.rst

ericholscher · 2019-10-10T16:16:02Z

docs/development/design/organizations.rst

+- Subscription
+
+This app can be named *subscriptions*.
+We can get around the table names and migrations by setting the explicitly the table name to `organizations_<model>`,


I think we can clean it up later. It doesn't need to be done now.

ericholscher · 2019-10-10T16:16:51Z

docs/development/design/organizations.rst

+In the community site we run an initial migration,
+for the corporate site we run a fake migration.


I think the plan is to just squash the migrations and start with the current state as initial. This makes sense to me, as nobody will be needing to catch up to the current state, and it's effectively a new app in the .org.

ericholscher · 2019-10-10T16:20:06Z

docs/development/design/organizations.rst

+For managers and querysets that depend on subscriptions,
+we can use our pattern to make overridable classes (inheriting from ``SettingsOverrideObject``).
+
+Templates, urls, views, forms, notifications, signals, tasks can be moved later


I think it would be useful to have a bit more of this fleshed out. I think that moving the models is definitely the best first step, but it won't do us much good without migrating the queryset permission logic as well.

docs/development/design/organizations.rst

agjohnson · 2019-10-14T16:38:54Z

docs/development/design/organizations.rst

+
+For the community site probably this approach isn't the best,
+since we always serve docs publicly from ``slug.readthedocs.io``.
+And most of the users don't have a custom domain.


What is our plan for slugs for organization projects in community then? Are we not using the organization slug at all? I have concerns about supporting both patterns at once. A collision is introduced if you slug a project with slug foo-something and an organization project for organization slug foo and project name something -- ie both produce the same slug.

I'm suggesting to use the project slug for users and orgs for .org. So we have foo-something and something.

Like if a user from the pallets org creates a project named flask, the slug would be flask, no pallets-flask.

👍 I'd agree, that seems like a good pattern for the community side.

agjohnson · 2019-10-14T16:44:16Z

docs/development/design/organizations.rst

+Changes that aren't needed immediately after the migration,
+but that should be done:
+
+Edit the current querysets, modify/add UI elements, and add new endpoints to the API (v3 only).


Modifying the UI is not going to be a future change, it will be tied directly to this work. We should probably have an idea of at least what UI components are likely to require changes. We won't be able to just copy the UI bits into community as we've discussed structural changes -- supporting user projects and organization projects for instance.

I just put some pieces not sure if we want to copy most of the UI from .com or make something different (especially for listing and detail of orgs)?

If we're not going to enable this on the community site yet, and we're going to do a two step process -- move the code over, and then sometime later actually enable organizations on the community codebase -- then we can worry about UI later.

Do we want to source templates for organizations from the commercial repo or move to the community repo?

Yes, it's a two step migration.

Do we want to source templates for organizations from the commercial repo or move to the community repo?

Good question, I think we can move the urls/views later, that way the templates can live in .com in the meantime and is easy to not enable organization in the community site.

agjohnson · 2019-10-16T18:47:55Z

The plan seems pretty close. We should codify and resolve all of the conversations we had here into the design document so we don't lose some of these decisions.

The one thing I would like to have more of a plan around is the operations changes that we'll need to have considered. If we are going to skip a downtime event due to database/migration changes on the initial deploy, we should outline the next phase of this work in a separate issue and define what we're pushing off.

stsewd · 2019-10-16T22:26:10Z

We should codify and resolve all of the conversations we had here into the design document so we don't lose some of these decisions

Done

The one thing I would like to have more of a plan around is the operations changes that we'll need to have considered. If we are going to skip a downtime event due to database/migration changes on the initial deploy, we should outline the next phase of this work in a separate issue and define what we're pushing off.

I did an overview of what is needed if we don't want to rename tables by ourselves https://github.com/readthedocs/readthedocs-corporate/pull/686

Nothing complex there, we just need to run a fake migration. Tested it locally.

And when the app is moved to .org, the commercial site won't need a migration.

agjohnson · 2019-10-23T23:14:07Z

No one else has raised any more issues on this and the work has already been started before merge here. Not much reason to keep this PR open.

stsewd requested a review from a team July 18, 2019 20:11

stsewd added Needed: design decision A core team decision is required PR: work in progress Pull request is not ready for full review labels Jul 18, 2019

ericholscher reviewed Aug 26, 2019

View reviewed changes

stsewd added 4 commits August 27, 2019 11:53

First draft for organizations design document

08b7941

Namespace

fa35338

More about migration

073af09

More details on moving organizations

92821db

stsewd force-pushed the organizations-design-doc branch from 7a22bb3 to 92821db Compare August 27, 2019 19:44

stsewd removed the PR: work in progress Pull request is not ready for full review label Sep 4, 2019

stsewd requested a review from a team September 4, 2019 17:50

ericholscher requested a review from davidfischer September 30, 2019 16:21

davidfischer reviewed Oct 4, 2019

View reviewed changes

humitos reviewed Oct 4, 2019

View reviewed changes

stsewd and others added 4 commits October 7, 2019 12:30

Typos

d6cd454

Co-Authored-By: David Fischer <djfische@gmail.com>

Feedback

c15f903

Typo

35f997e

Merge branch 'master' into organizations-design-doc

c84df06

ericholscher approved these changes Oct 10, 2019

View reviewed changes

stsewd added 2 commits October 10, 2019 18:35

Little improvements

13ff1bd

Merge branch 'master' into organizations-design-doc

1d9151a

agjohnson reviewed Oct 14, 2019

View reviewed changes

stsewd added 2 commits October 14, 2019 12:14

Add user interface to the design doc

0314454

Update doc

2bb089f

stsewd added 3 commits October 16, 2019 17:21

Clarification on design decisions

f2ffd14

Merge branch 'master' into organizations-design-doc

730b2e2

Typo

45e6c57

agjohnson merged commit 417e221 into readthedocs:master Oct 23, 2019

stsewd deleted the organizations-design-doc branch October 23, 2019 23:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Design doc for organizations #5958

Design doc for organizations #5958

stsewd commented Jul 18, 2019

ericholscher left a comment

ericholscher Aug 26, 2019

ericholscher Aug 26, 2019

davidfischer left a comment

humitos left a comment

humitos Oct 4, 2019

stsewd Oct 7, 2019

ericholscher Oct 10, 2019

humitos Oct 4, 2019

stsewd Oct 7, 2019

humitos Oct 8, 2019

stsewd Oct 8, 2019 •

edited

Loading

ericholscher Oct 10, 2019 •

edited

Loading

humitos commented Oct 10, 2019

stsewd commented Oct 10, 2019

ericholscher left a comment

ericholscher Oct 10, 2019

ericholscher Oct 10, 2019 •

edited

Loading

ericholscher Oct 10, 2019

agjohnson Oct 14, 2019

stsewd Oct 14, 2019

stsewd Oct 14, 2019 •

edited

Loading

agjohnson Oct 16, 2019

agjohnson Oct 14, 2019

stsewd Oct 14, 2019

agjohnson Oct 16, 2019

stsewd Oct 16, 2019

agjohnson commented Oct 16, 2019

stsewd commented Oct 16, 2019 •

edited

Loading

agjohnson commented Oct 23, 2019

		In the community site we run an initial migration,
		for the corporate site we run a fake migration.

Design doc for organizations #5958

Design doc for organizations #5958

Conversation

stsewd commented Jul 18, 2019

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidfischer left a comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd Oct 8, 2019 • edited Loading

Choose a reason for hiding this comment

ericholscher Oct 10, 2019 • edited Loading

Choose a reason for hiding this comment

humitos commented Oct 10, 2019

stsewd commented Oct 10, 2019

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher Oct 10, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd Oct 14, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson commented Oct 16, 2019

stsewd commented Oct 16, 2019 • edited Loading

agjohnson commented Oct 23, 2019

stsewd Oct 8, 2019 •

edited

Loading

ericholscher Oct 10, 2019 •

edited

Loading

ericholscher Oct 10, 2019 •

edited

Loading

stsewd Oct 14, 2019 •

edited

Loading

stsewd commented Oct 16, 2019 •

edited

Loading