7.9 KiB
comments | type | stage | group | info | description |
---|---|---|---|---|---|
false | index, dev | Data Stores | Tenant Scale | See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines | Development Guidelines: learn about organization when developing GitLab. |
Organization
The Organization initiative focuses on reaching feature parity between SaaS and self-managed installations.
Consolidate groups and projects
One facet of the Organization initiative is to consolidate groups and projects, addressing the feature disparity between them. Some features, such as epics, are only available at the group level. Some features, such as issues, are only available at the project level. Other features, such as milestones, are available to both groups and projects.
We receive many requests to add features either to the group or project level. Moving features around to different levels is problematic on multiple levels:
- It requires engineering time to move the features.
- It requires UX overhead to maintain mental models of feature availability.
- It creates redundant code.
When features are copied from one level (project, group, or instance) to another, the copies often have small, nuanced differences between them. These nuances cause extra engineering time when fixes are needed, because the fix must be copied to several locations. These nuances also create different user experiences when the feature is used in different places.
A solution for this problem is to consolidate groups and projects into a single
entity, namespace
. The work on this solution is split into several phases and
is tracked in epic 6473.
Phase 1
- Phase 1 epic.
- Goals:
- Ensure every project receives a corresponding record in the
namespaces
table withtype='Project'
. - For user namespaces, the type changes from
NULL
toUser
.
- Ensure every project receives a corresponding record in the
We should make sure that projects, and the project namespace, are equivalent:
- Create project: use Rails callbacks to ensure a new project namespace is
created for each project. Project namespace records should contain
created_at
andupdated_at
attributes equal to the project'screated_at
/updated_at
attributes. - Update project: use the
after_save
callback in Rails to ensure some attributes are kept in sync between project and project namespaces. Readproject#after_save
for more information. - Delete project: use FKs cascade delete or Rails callbacks to ensure when a
Project
or itsProjectNamespace
is removed, its correspondingProjectNamespace
orProject
is also removed. - Transfer project to a different group: make sure that when a project is transferred, its corresponding project namespace is transferred to the same group.
- Transfer group: make sure when transferring a group that all of its sub-projects, either direct or through descendant groups, have their corresponding project namespaces transferred correctly as well.
- Export or import project
- Export project continues to export only the project, and not its project namespace, in this phase. The project namespace does not contain any specific information to export at this point. Eventually we want the project namespace to be exported as well.
- Import project creates a new project, so the project namespace is created through
Rails
after_save
callback on the project model.
- Export or import group: when importing or exporting a
Group
, projects are not included in the operation. If that feature is changed to includeProject
when its group is imported or exported, the logic must include their corresponding project namespaces in the import or export.
After ensuring these points, run a database migration to create a ProjectNamespace
record for every Project
. Project namespace records created during the migration
should have created_at
and updated_at
attributes set to the migration runtime.
The project namespaces' created_at
and updated_at
attributes would not match
their corresponding project's created_at
and updated_at
attributes. We want
the different dates to help audit any of the created project namespaces, in case we need it.
After this work completes, we must migrate data as described in
Backfill ProjectNamespace
for every Project.
Phase 2
- Phase 2 epic.
- Goal: Link
ProjectNamespace
to other entities on the database level.
In this phase:
- Communicate the changes company-wide at the engineering level. We want to make engineers aware of the upcoming changes, even though teams are not expected to collaborate actively until phase 3.
- Raise awareness to avoid regressions, and conflicting or duplicate work that can be dealt with before phase 3.
Phase 3
-
Goal: Achieve feature parity between the namespace types. Problems to solve as part of this phase:
-
Routes handling through
ProjectNamespace
rather thanProject
. -
Memberships handling.
-
Policies handling.
-
Import and export.
-
Other interactions between project namespace and project models.
Phase 3 is when the active migration of features from Project
to ProjectNamespace
,
or directly to Namespace
, happens.
How to plan features that interact with Group and ProjectNamespace
As of now, every Project in the system has a record in the namespaces
table. This makes it possible to
use common interface to create features that are shared between Groups and Projects. Shared behavior can be added using
a concerns mechanism. Because the Namespace
model is responsible for UserNamespace
methods as well, it is discouraged
to use the Namespace
model for shared behavior for Projects and Groups.
Resource-based features
To migrate resource-based features, existing functionality will need to be supported. This can be achieved in two Phases.
Phase 1 - Setup
- Link into the namespaces table
- Add a column to the table
- For example, in issues a
project id
points to the projects table. We need to establish a link to thenamespaces
table. - Modify code so that any new record already has the correct data in it
- Backfill
Phase 2 - Prerequisite work
- Investigate the permission model as well as any performance concerns related to that.
- Permissions need to be checked and kept in place.
- Investigate what other models need to support namespaces for functionality dependent on features you migrate in Phase 1.
- Adjust CRUD services and APIs (REST and GraphQL) to point to the new column you added in Phase 1.
- Consider performance when fetching resources.
Introducing new functionality is very much dependent on every single team and feature.
Settings-related features
Right now, cascading settings are available for NamespaceSettings
. By creating ProjectNamespace
,
we can use this framework to make sure that some settings are applicable on the project level as well.
When working on settings, we need to make sure that:
- They are not used in
join
queries or modify those queries. - Updating settings is taken into consideration.
- If we want to move from project to project namespace, we follow a similar database process to the one described in Phase 1.
Related topics
- Consolidating groups and projects architecture documentation
- Organization user documentation