maxmustermann/gitlab
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Revise doc on groups and projects consolidation

Browse source
This commit is contained in:
Amy Qualls 2021-11-04 20:23:34 +00:00 committed by charlie ablett
parent ec9d315a1d
commit 35a5632118
3 changed files with 91 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/architecture/blueprints/consolidating_groups_and_projects/index.md
View file

@ -139,7 +139,7 @@ The initial iteration will provide a framework to house features under `Namespac
1. **Tier**: Is there any tier functionality that is differentiated by projects and groups?
1. **Documentation**: Is the structure and content of documentation impacted by these changes at all?
1. **Solution proposal**:
- Think big: This analysis provides a great opportunity to zoom out and consider the feature UX as a whole. How could you make this feature lovable based on the new structure, inheritance, and capabilities afforded by `Namespaces`? Is there any UI which doesn't comply with Pajamas?
- Think big: This analysis provides a great opportunity to zoom out and consider the feature UX as a whole. How could you make this feature lovable based on the new structure, inheritance, and capabilities afforded by `Namespaces`? Is there any UI which doesn't comply with Pajamas?
- Start small: What are the product changes that need to be made to assist with the migration?
- Move fast: Prioritise these solution ideas, document in issues, and create a roadmap for implementation.
@ -170,3 +170,7 @@ DRIs:
| Design | Nick Post |
<!-- vale gitlab.Spelling = YES -->
## Related topics
- [Workspaces developer documentation](../../../development/workspaces/index.md)

139
doc/development/workspaces/index.md
View file

@ -9,87 +9,112 @@ description: "Development Guidelines: learn about workspaces when developing Git
# Workspaces
[Read more](../../user/workspace/index.md) about the workspaces initiative.
The [Workspaces initiative](../../user/workspace/index.md) focuses on reaching feature parity between
SaaS and self-managed installations.
## Consolidate Groups and Projects
## Consolidate groups and projects
- [Architecture blueprint](../../architecture/blueprints/consolidating_groups_and_projects/index.md)
Consolidate Groups and Projects is one facet of the workspaces initiative, addressing the feature disparity between
groups and projects.
One facet of the workspaces 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.
There is feature disparity between groups and projects. Some features only available at group level (for example epics).
Some features only available at project level (for example issues). And some features available at both levels
(for example labels, milestones).
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:
We get more and more requests to get one feature or another added to either group or project level. This takes
engineering time, to just move features around to different levels. This also adds a UX overhead of keeping a mental
model of which features are available at which level.
- It requires engineering time to move the features.
- It requires UX overhead to maintain mental models of feature availability.
- It creates redundant code.
This also creates lots of redundant code. Features get copied from project, to group to instance level with small
nuances between them. This also causes extra maintenance, when something needs to be fixed. The fix is copied to
several locations. This also creates different user experience for the same feature but in the different locations.
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.
To solve this we are moving towards consolidating groups and projects into a single entity, namespace. The work on this
solution is split into several phases and is tracked in [epic 6473](https://gitlab.com/groups/gitlab-org/-/epics/6473).
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](https://gitlab.com/groups/gitlab-org/-/epics/6473).
### Phase 1
Epic tracking [Phase 1](https://gitlab.com/groups/gitlab-org/-/epics/6697)
- [Phase 1 epic](https://gitlab.com/groups/gitlab-org/-/epics/6697).
- **Goals**:
1. Ensure every project receives a corresponding record in the `namespaces`
table with `type='Project'`.
1. For user namespaces, the type changes from `NULL` to `User`.
Goal of Phase 1 is to ensure that every project gets a corresponding record in `namespaces` table with `type='Project'`.
For user namespaces, type changes from `NULL` to `User`.
We should make sure that projects, and the project namespace, are equivalent:
Places where we should make sure project and project namespace go hand in hand:
- **Create project:** use Rails callbacks to ensure a new project namespace is
created for each project. Project namespace records should contain `created_at` and
`updated_at` attributes equal to the project's `created_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.
Read [`project#after_save`](https://gitlab.com/gitlab-org/gitlab/blob/6d26634e864d7b748dda0e283eb2477362263bc3/app/models/project.rb#L101-L101)
for more information.
- **Delete project:** use FKs cascade delete or Rails callbacks to ensure when a `Project`
or its `ProjectNamespace` is removed, its corresponding `ProjectNamespace` or `Project`
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 include `Project` when its group is
imported or exported, the logic must include their corresponding project namespaces
in the import or export.
- Create project.
- Use Rails callbacks to ensure a new project namespace is created for each project.
- In this case project namespace records should have `created_at`/`updated_at` attributes equal to project's `created_at`/`updated_at` attributes.
- Update Project.
- Use Rails `after_save` callback to ensure some attributes are kept in sync between project and project namespaces,
see [project#after_save](https://gitlab.com/gitlab-org/gitlab/blob/6d26634e864d7b748dda0e283eb2477362263bc3/app/models/project.rb#L101-L101).
- Delete project.
- Use FKs cascade delete or Rails callbacks to ensure when either a `Project` or its `ProjectNamespace` is removed its
corresponding `ProjectNamespace` or `Project` respectively is removed as well.
- 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/import project.
- Export project would continue to only export the project and not its project namespace in this phase. Project
namespace does not contain any specific information that has to be exported at this point. Eventually we want the
project namespace to be exported as well.
- Import creates a new project, so project namespace is created through Rails `after_save` callback on the project model.
- Export/import group.
- As of this writing, when importing or exporting a `Group`, `Project`s are not included in the operation. If that functionality is changed to include `Project` when its Group is imported/exported, the logic must be sure to include their corresponding project namespaces in the import/export.
After ensuring the above points, we plan to run a DB migration to create a `ProjectNamespace` record for every `Project`.
Project namespace records created during migration should have `created_at`/`updated_at` attributes set to migration
runtime. That means that project namespaces `created_at`/`updated_at` attributes don't match their corresponding
project's `created_at`/`updated_at` attributes. We want the different dates to help audit any of the created project
namespaces, in case we need it. We plan to run the back-filling migration in 14.5 milestone.
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](https://gitlab.com/gitlab-org/gitlab/-/issues/337100).
### Phase 2
Epic tracking [Phase 2](https://gitlab.com/groups/gitlab-org/-/epics/6768)
- [Phase 2 epic](https://gitlab.com/groups/gitlab-org/-/epics/6768).
- **Goal**: Make `ProjectNamespace` the front entity to interact with instead of `Project`.
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.
The focus of this phase is to make `ProjectNamespace` the front entity to interact with instead of `Project` .
Problems to solve as part of this phase:
- Routes handling through project namespace rather than project.
- Routes handling through `ProjectNamespace` rather than `Project`.
- Memberships handling.
- Policies handling.
- Import/export.
- Import and export.
- Other interactions between project namespace and project models.
Communicate the changes company wide at the engineers level. We want engineers to be aware of the upcoming changes even
though active collaboration of teams is expected only in phase 3. Raise awareness to avoid regressions, conflicting or duplicate work
that can be taken care of even before phase 3.
### Phase 3
Epic tracking [Phase 3](https://gitlab.com/groups/gitlab-org/-/epics/6585)
- [Phase 3 epic](https://gitlab.com/groups/gitlab-org/-/epics/6585).
- **Goal**: Feature parity between the namespace types.
The focus of this phase is to get feature parity between the namespace types. Phase 3 is when active migration
of features from `Project` to `ProjectNamespace` or directly to `Namespace` happens.
Phase 3 is when the active migration of features from `Project` to `ProjectNamespace`,
or directly to `Namespace`, happens.
## Related topics
- [Consolidating groups and projects](../../architecture/blueprints/consolidating_groups_and_projects/index.md)
architecture documentation
- [Workspace user documentation](../../user/workspace/index.md)

4
doc/user/workspace/index.md
View file

@ -46,3 +46,7 @@ The following provide a preview to the Workspace concept.
![Admin Overview](img/Admin_Settings.png)
![Admin Overview](img/hardware_settings.png)
## Related topics
- [Workspaces developer documentation](../../development/workspaces/index.md)