Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Design doc for organizations #5958

Merged
merged 15 commits into from Oct 23, 2019

Conversation

@stsewd
Copy link
Member

stsewd commented Jul 18, 2019

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.

@stsewd stsewd requested a review from readthedocs/core Jul 18, 2019
Copy link
Member

ericholscher left a comment

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 Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
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.

This comment has been minimized.

Copy link
@ericholscher

ericholscher Aug 26, 2019

Member

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


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.

This comment has been minimized.

Copy link
@ericholscher

ericholscher Aug 26, 2019

Member

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.

@stsewd stsewd force-pushed the stsewd:organizations-design-doc branch from 7a22bb3 to 92821db Aug 27, 2019
@stsewd stsewd requested a review from readthedocs/core Sep 4, 2019
@ericholscher ericholscher requested a review from davidfischer Sep 30, 2019
Copy link
Contributor

davidfischer left a comment

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 Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
Copy link
Member

humitos left a comment

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 Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
- 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>`,

This comment has been minimized.

Copy link
@humitos

humitos Oct 4, 2019

Member

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.

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 7, 2019

Author Member

That would generate some downtime.

This comment has been minimized.

Copy link
@ericholscher

ericholscher Oct 10, 2019

Member

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

In the community site we run an initial migration,
for the corporate site we run a fake migration.
Comment on lines +110 to +111

This comment has been minimized.

Copy link
@humitos

humitos Oct 4, 2019

Member

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

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 7, 2019

Author Member

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.

This comment has been minimized.

Copy link
@humitos

humitos Oct 8, 2019

Member

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.

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 8, 2019

Author Member

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

This comment has been minimized.

Copy link
@ericholscher

ericholscher Oct 10, 2019

Member

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 Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
stsewd and others added 4 commits Oct 7, 2019
Typos
Co-Authored-By: David Fischer <djfische@gmail.com>
@humitos

This comment has been minimized.

Copy link
Member

humitos commented Oct 10, 2019

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

This comment has been minimized.

Copy link
Member Author

stsewd commented Oct 10, 2019

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.

Copy link
Member

ericholscher left a comment

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 Outdated Show resolved Hide resolved
docs/development/design/organizations.rst Outdated Show resolved Hide resolved
- 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>`,

This comment has been minimized.

Copy link
@ericholscher

ericholscher Oct 10, 2019

Member

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

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

This comment has been minimized.

Copy link
@ericholscher

ericholscher Oct 10, 2019

Member

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.

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

This comment has been minimized.

Copy link
@ericholscher

ericholscher Oct 10, 2019

Member

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 Outdated Show resolved Hide resolved

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.

This comment has been minimized.

Copy link
@agjohnson

agjohnson Oct 14, 2019

Contributor

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.

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 14, 2019

Author Member

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

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 14, 2019

Author Member

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

This comment has been minimized.

Copy link
@agjohnson

agjohnson Oct 16, 2019

Contributor

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

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).

This comment has been minimized.

Copy link
@agjohnson

agjohnson Oct 14, 2019

Contributor

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.

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 14, 2019

Author Member

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)?

This comment has been minimized.

Copy link
@agjohnson

agjohnson Oct 16, 2019

Contributor

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?

This comment has been minimized.

Copy link
@stsewd

stsewd Oct 16, 2019

Author Member

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.

stsewd added 2 commits Oct 14, 2019
@agjohnson

This comment has been minimized.

Copy link
Contributor

agjohnson commented Oct 16, 2019

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

This comment has been minimized.

Copy link
Member Author

stsewd commented Oct 16, 2019

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 readthedocs/readthedocs-corporate#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

This comment has been minimized.

Copy link
Contributor

agjohnson commented Oct 23, 2019

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.

@agjohnson agjohnson merged commit 417e221 into readthedocs:master Oct 23, 2019
2 checks passed
2 checks passed
continuous-documentation/read-the-docs Read the Docs build succeeded!
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@stsewd stsewd deleted the stsewd:organizations-design-doc branch Oct 23, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.