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
Merged

Conversation

stsewd
Copy link
Member

@stsewd 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 Jul 18, 2019
@stsewd stsewd added Needed: design decision PR: work in progress labels Jul 18, 2019
Copy link
Member

@ericholscher 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.
Copy link
Member

@ericholscher ericholscher Aug 26, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member

@ericholscher ericholscher Aug 26, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 organizations-design-doc branch from 7a22bb3 to 92821db Compare Aug 27, 2019
@stsewd stsewd removed the PR: work in progress label Sep 4, 2019
@stsewd stsewd requested a review from Sep 4, 2019
@ericholscher ericholscher requested a review from davidfischer Sep 30, 2019
Copy link
Contributor

@davidfischer 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 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 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>`,
Copy link
Member

@humitos humitos Oct 4, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@stsewd stsewd Oct 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would generate some downtime.

Copy link
Member

@ericholscher ericholscher Oct 10, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member

@humitos humitos Oct 4, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@stsewd stsewd Oct 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@humitos humitos Oct 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@stsewd stsewd Oct 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@ericholscher ericholscher Oct 10, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
@humitos
Copy link
Member

@humitos 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
Copy link
Member Author

@stsewd 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 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
docs/development/design/organizations.rst 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>`,
Copy link
Member

@ericholscher ericholscher Oct 10, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member

@ericholscher ericholscher Oct 10, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

@ericholscher ericholscher Oct 10, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
docs/development/design/organizations.rst 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.
Copy link
Contributor

@agjohnson agjohnson Oct 14, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@stsewd stsewd Oct 14, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@stsewd stsewd Oct 14, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@agjohnson agjohnson Oct 16, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 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).
Copy link
Contributor

@agjohnson agjohnson Oct 14, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@stsewd stsewd Oct 14, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@agjohnson agjohnson Oct 16, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

@stsewd stsewd Oct 16, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

@agjohnson 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
Copy link
Member Author

@stsewd 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
Copy link
Contributor

@agjohnson 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
@stsewd stsewd deleted the 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
Labels
Needed: design decision
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants