Add compatibility guidelines to API documentation

Description

When working on the API, there is no documentation describing a practice, or strategy for backwards compatibility. We should add a section describing how to handle breaking changes. Maybe answer a few questions like:

• When should you ensure backwards compatibility?
• How to track old code/features/methods that can be removed after major versions
• Formalities for upgrading to API versions with breaking changes

Proposal

Add a section or completely new document in https://docs.gitlab.com/ce/api/

Mentioned in merge request !6355 (closed)

Added ~15078 ~13884 labels

I think this is a good idea. We should add this to the Developer Documentation with more detailed guidelines and then a short section on the API README with a link to the developer documentation if they want more information.

cc: @zj @razer6

Good points, my opinion:

When should you ensure backwards compatibility?

Lets follow SemVer here and not drop any endpoints in a major point release line. Next major point we have the ability to drop a couple of endpoints where needed. What exactly is a bug and can be fixed now already should be decided on a case by case basis.

How to track old code/features/methods that can be removed after major versions

I've created gitlab-org/gitlab-ce#20070 to track all endpoints up for changes. Mind you, this issue is for tracking purposes only, not for discussions if it should be dropped/changed. Thats what the linked issue is for.

Formalities for upgrading to API versions with breaking changes

If the endpoint changes from say: /project/fork/:id to /project/:id/fork we could, and should already support the latter. The former is dropped on the 9.0 release. If its not yet possible to support a new endpoint we shouldn't and change where needed in the next major point release.

@brianp Thanks for asking these questions, if you have more, please ask

moved to gitlab#6404

Hey!

GitLab is moving all development for both GitLab Community Edition and Enterprise Edition into a single codebase. The current gitlab-ce repository will become a read-only mirror, without any proprietary code. All development is moved to the current gitlab-ee repository, which we will rename to just gitlab in the coming weeks. As part of this migration, issues will be moved to the current gitlab-ee project.

If you have any questions about all of this, please ask them in our dedicated FAQ issue.

https://gitlab.com/gitlab-org/gitlab-ee/issues/13855

You can also find more information here:

• https://gitlab.com/gitlab-org/gitlab-ee/issues/13304
• https://about.gitlab.com/2019/08/23/a-single-codebase-for-gitlab-community-and-enterprise-edition/

Frequently Asked Questions

For an up to date list of questions and answers, please take a look at https://gitlab.com/gitlab-org/gitlab-ee/issues/13855

What will we do with the repository names?

https://gitlab.com/gitlab-org/gitlab-ee/ will become https://gitlab.com/gitlab-org/gitlab, and https://gitlab.com/gitlab-org/gitlab-ce will become https://gitlab.com/gitlab-org/gitlab-foss.

Why rename gitlab-ce to gitlab-foss?

Using "gitlab" and "gitlab-ce" would be confusing, so we decided to rename gitlab-ce to gitlab-foss to make the purpose of this FOSS repository more clear

I created a merge requests for CE, and this got closed. What do I need to do?

You will need to create a merge request at https://gitlab.com/gitlab-org/gitlab-ee/. This link will eventually redirect to https://gitlab.com/gitlab-org/gitlab.

How does the licensing work in this new setup?

Everything in the ee/ directory is proprietary. Everything else is free and open source software. If your merge request does not change anything in the ee/ directory, the process of contributing changes is the same as when using the gitlab-ce repository.

Will you accept merge requests on the gitlab-ce/gitlab-foss project after it has been renamed?

No. Merge requests submitted to this project will be closed automatically.

Will I still be able to view old issues and merge requests in gitlab-ce/gitlab-foss?

Yes.

How will this affect users of GitLab CE using Omnibus?

No changes will be necessary, as the packages built remain the same.

How will this affect users of GitLab CE that build from source?

Once the project has been renamed, you will need to change your Git remotes to use this new URL. GitLab will take care of redirecting Git operations so there is no hard deadline, but we recommend doing this as soon as the projects have been renamed.

Where can I see a timeline of the remaining steps?

https://gitlab.com/gitlab-org/gitlab-ee/issues/13304

Will community contributions submitted to the new "gitlab" repository be available in the new gitlab-foss repository?

Yes, these changes will be synced to gitlab-foss automatically, several times per day.

locked this issue

mentioned in merge request !14785