|
| 1 | +Organizations |
| 2 | +============= |
| 3 | + |
| 4 | +Currently we don't support organizations in the community site |
| 5 | +(a way to group different projects), |
| 6 | +we only support individual accounts. |
| 7 | + |
| 8 | +Several integrations that we support like GitHub and Bitbucket have organizations, |
| 9 | +where users group their repositories and manage them in groups rather than individually. |
| 10 | + |
| 11 | +Why move organizations in the community site? |
| 12 | +--------------------------------------------- |
| 13 | + |
| 14 | +We support organizations in the commercial site, |
| 15 | +having no organizations in the community site makes the code maintenance difficult for Read the Docs developers. |
| 16 | +Having organizations in the community site will make the differences between both more easy to manage. |
| 17 | + |
| 18 | +Users from the community site can have organizations in external sites from where we import their projects |
| 19 | +(like GitHub, Gitlab). |
| 20 | +Currently users have all projects from different organizations in their account. |
| 21 | +Having not a clear way to group/separate those. |
| 22 | + |
| 23 | +We are going to first move the code, |
| 24 | +and after that enable the feature on the community site. |
| 25 | + |
| 26 | +How are we going to support organizations? |
| 27 | +------------------------------------------ |
| 28 | + |
| 29 | +Currently only users can own projects in the community site. |
| 30 | +With organizations this is going to change to: |
| 31 | +Users and organizations can own projects. |
| 32 | + |
| 33 | +With this, the migration process would be straightforward for the community site. |
| 34 | + |
| 35 | +For the commercial site we are only to allow organizations to own projects for now |
| 36 | +(since the we have only subscriptions per organizations). |
| 37 | + |
| 38 | +What features of organizations are we going to support? |
| 39 | +------------------------------------------------------- |
| 40 | + |
| 41 | +We have the following features in the commercial site that we don't have on the community site: |
| 42 | + |
| 43 | +- Owners |
| 44 | +- Teams |
| 45 | +- Permissions |
| 46 | +- Subscriptions |
| 47 | + |
| 48 | +Owners should be included to represent owners of the current organization. |
| 49 | + |
| 50 | +Teams, this is also handy to manage access to different projects under the same organization. |
| 51 | + |
| 52 | +Permissions, |
| 53 | +currently we have two type of permissions for teams: admin and read only. |
| 54 | +Read only permissions doesn't make sense in the community site since we only support public projects/versions |
| 55 | +(we do support private versions now, but we are planning to remove those). |
| 56 | +So, we should only support admin permissions for teams. |
| 57 | + |
| 58 | +Subscriptions, this is only valid for the corporate site, |
| 59 | +since we don't charge for use in the community site. |
| 60 | + |
| 61 | +How to migrate current projects |
| 62 | +------------------------------- |
| 63 | + |
| 64 | +Since we are not replacing the current implementation, |
| 65 | +we don't need to migrate current projects from the community site nor from the corporate site. |
| 66 | + |
| 67 | +How to migrate the organizations app |
| 68 | +------------------------------------ |
| 69 | + |
| 70 | +The migration can be split in: |
| 71 | + |
| 72 | +#. Remove/simplify code from the organizations app on the corporate site. |
| 73 | +#. Isolate/separate models and code that isn't going to be moved. |
| 74 | +#. Start by moving the models, managers, and figure out how to handle migrations. |
| 75 | +#. Move the rest of the code as needed. |
| 76 | +#. Activate organizations app on the community site. |
| 77 | +#. Integrate the code from the community site to the new code. |
| 78 | +#. UI changes |
| 79 | + |
| 80 | +We should start by removing unused features and dead code from the organizations in the corporate site, |
| 81 | +and simplify existing code if possible (some of this was already done). |
| 82 | + |
| 83 | +Isolate/separate the models to be moved from the ones that aren't going to be moved. |
| 84 | +We should move the models that aren't going to me moved to another app. |
| 85 | + |
| 86 | +- Plan |
| 87 | +- PlanFeature |
| 88 | +- Subscription |
| 89 | + |
| 90 | +This app can be named *subscriptions*. |
| 91 | +We can get around the table names and migrations by setting the explicitly the table name to ``organizations_<model>``, |
| 92 | +and doing a fake migration. |
| 93 | +Following suggestions in https://stackoverflow.com/questions/48860227/moving-multiple-models-from-one-django-app-to-another, |
| 94 | +that way we avoid having any downtime during the migration and any inconvenient caused from renaming the tables manually. |
| 95 | + |
| 96 | +Code related to subscriptions should be moved out from the organizations app. |
| 97 | + |
| 98 | +After that, it should be easier to move the organizations *app* (or part of it) |
| 99 | +to the community site (and no changes to table names would be required). |
| 100 | + |
| 101 | +We start by moving the models. |
| 102 | + |
| 103 | +- Organization |
| 104 | +- OrganizationOwner |
| 105 | +- Team |
| 106 | +- TeamInvite |
| 107 | +- TeamMember |
| 108 | + |
| 109 | +Migrations aren't moved, since all current migrations depend on other models that aren't |
| 110 | +going to be moved. |
| 111 | +In the community site we run an initial migration, |
| 112 | +for the corporate site we run a fake migration. |
| 113 | +The migrations left from the commercial site can be removed after that. |
| 114 | + |
| 115 | +For managers and querysets that depend on subscriptions, |
| 116 | +we can use our pattern to make overridable classes (inheriting from ``SettingsOverrideObject``). |
| 117 | + |
| 118 | +Templates, urls, views, forms, notifications, signals, tasks can be moved later |
| 119 | +(we just need to make use of the models from the ``readthedocs.organizations`` module). |
| 120 | + |
| 121 | +If we decide to integrate organizations in the community site, |
| 122 | +we can add/move the UI elements and enable the app. |
| 123 | + |
| 124 | +After the app is moved, |
| 125 | +we can move more code that depends on organizations to the community site. |
| 126 | + |
| 127 | +Namespace |
| 128 | +--------- |
| 129 | + |
| 130 | +Currently we use the project's slug as namespace, |
| 131 | +in the commercial site we use the combination of ``organization.slug`` + ``project.slug`` as namespace, |
| 132 | +since in the corporate site we don't care so much about a unique namespace between all users, |
| 133 | +but a unique namespace per organization. |
| 134 | + |
| 135 | +For the community site probably this approach isn't the best, |
| 136 | +since we always serve docs publicly from ``slug.readthedocs.io``. |
| 137 | +And most of the users don't have a custom domain. |
| 138 | + |
| 139 | +The corporate site will use ``organization.slug`` + ``project.slug`` as slug, |
| 140 | +And the community site will always use ``project.slug`` as slug, even if the project belongs to an organization. |
| 141 | + |
| 142 | +We need to refactor the way we get the namespace to be more easy to manage in both sites. |
| 143 | + |
| 144 | +Future Changes |
| 145 | +-------------- |
| 146 | + |
| 147 | +Changes that aren't needed immediately after the migration, |
| 148 | +but that should be done: |
| 149 | + |
| 150 | +- UI for organizations in the community site. |
| 151 | +- Add new endpoints to the API (v3 only). |
| 152 | +- Make the relationship between the models ``Organization`` and ``Project`` one to many |
| 153 | + (currently many to many). |
0 commit comments