Start deprecating old VCS support

[humitos]

Currently, we support the following VCS in our platform:

• git (git)
• bazaar (bzr)
• mercurial (hg)
• subversion (svn)

I'd like to start a conversation about the possibility to deprecate the ones that are mainly not used. In particular, subversion. I went ahead and took some numbers from our platform to find out how much each of them is used:

Number of projects using VCS

• git: 247,599
• hg: 1,773
• bzr: 1,765
• svn: 1,673

Number of projects using VCS with a build in the last 30 days

• git: 14,141
• hg: 46
• svn: 31
• bzr: 12

Number of projects using VCS with a successful build in the last 30 days

• git: 11,532
• hg: 37
• svn: 2
• bzr: 0

Also note that I'm not discarding spam projects. So, these numbers are lower.

---

I'd propose to start removing svn (and probably bzr as well) from the UI to avoid new projects being imported using these VCS. Then, the next step would be to communicate projects that are not spam that we are deprecating support for the VCS they are using.

Also note that to select svn and/or bzr users have to import the project manually, which gives them a worse UX of the whole platform: manual import, manual webhook setup, etc.

This will allow us to not maintain features that almost nobody uses but consume our time in different ways.

Edit: fix numbers that were wrong (missed a DISTINCT in the query)

[agjohnson]

It would be helpful to know when these projects were created as well. That is, were bzr and svn projects mostly created 5 years ago? Git is obviously the primary vcs, but I would guess that new projects are even more leaning towards git. Also might be worth getting this information on hg as well.

I'm 👍 on deprecating support on svn and bzr. Slowly helps here: removal from the UI, then removing actual support in the backends. Though, given above, I doubt we get a lot of new projects coming in with either.

[humitos]

Notes from our meeting in January 😄 :

• Make a deprecation timeline (Remove from UI at this time?)
• Find projects to email (Valid build in last year) & email them
• Finally, deprecate/remove code

[agjohnson]

More notes: maybe it makes sense to scope this down to removing suggestions for bzr/hg in our docs, and point users to always use git. Code removal will be a ways out

[humitos]

I'm fine with removing this from the documentation as the first step. However, I think we are always pushing back on deprecating things properly with a hard final date. Finally, we end up with inconsistencies between our docs, our code, and what we want. I think we should start becoming more strict with deprecations, in particular with those that are not heavily used.

[agjohnson]

We could definitely add a bit more to the scope here. We get the most value here out of consistently pointing new users/projects to Git. The main point is that full removal and deprecation is going to be a fair amount of work and we won't get a whole lot of value out of this work.

As a big chunk of work, this doesn't yet have priority on our roadmap. But we can prioritize small steps in this direction more immediately.

Full deprecation and removal of this code will require UX/UI around unavailable VCS, contacting users, monitoring deprecation before code removal, etc. So, quite a lot considering we don't spend a lot of time with the code now anyways.

[humitos]

@agjohnson

But we can prioritize small steps in this direction more immediately.

We already have done this in our meeting from January #8840 (comment)

Full deprecation and removal of this code will require UX/UI around unavailable VCS, contacting users, monitoring deprecation before code removal, etc

I'd expect that the new UX/UI does not support these old VCS at all.

On the other hand, having a hard date of removal/end support communicated to users removes the requirement of a "monitoring" step.

So, quite a lot considering we don't spend a lot of time with the code now anyways.

I don't fully agree with this sentence. It's true that we don't touch this code too much, but simple things like #9424 require a lot more thinking, testing and QAing.

[agjohnson]

We already have done this in our meeting from January

Yeah we had some direction on this from that meeting, but in our roadmap planning call, this felt like an issue that we should bump out a quarter as it didn't really align. But we did agree we should have something from this on our radar.

That said, I think we're just describing making "Make a deprecation timeline (Remove from UI at this time?)" a few discrete steps. We can prioritize some smaller actions first

I'd expect that the new UX/UI does not support these old VCS at all.

Disallowing new project VCS choices could be another more immediate step.

On the other hand, having a hard date of removal/end support communicated to users removes the requirement of a "monitoring" step.

Though we will want to watch things periodically either way, we can expect new inbound support as we start the deprecation. We probably won't be lucky enough to get away with just emailing users and then returning to delete the code, there's some lump of work in the middle.

It's true that we don't touch this code too much, but simple things like #9424 require a lot more thinking, testing and QAing.

That's fair, there is work hiding here. At least for this next quarter, we hope to be touching the backend code less than we did in Q1/2, so this might not be a driving function of this change.

[humitos]

It would be helpful to know when these projects were created as well. That is, were bzr and svn projects mostly created 5 years ago?

This table shows the trending pretty well:

Screenshot from https://ethicalads.metabaseapp.com/question/238-projects-grouped-by-pub-date-month-and-vcs-type-success-build-in-last-year

This plot shows "projects with at least 1 success build in the last 12 months grouped by VCS type"

Screenshot from https://ethicalads.metabaseapp.com/question/239-projects-vcs-types-with-a-success-build-in-last-year

[humitos]

Some notes from the meeting that I was able to write down. Feel free to edit them or add context, comments.

• soft deprecation
• remove mentions from bzr and svn from all the documentation
• keep the code around
• avoid projects to select bzr and svn in the UI or similar places
• define a deprecation process to finally remove the code and break compatibility (see https://github.com/readthedocs/meta/discussions/46#discussioncomment-3587302)

[ericholscher]

I think we could even get rid of hg in the docs and drop downs. I like simplifying to be able to just support git would dramatically improve a lot of our messaging.

[benjaoming]

remove mentions from bzr and svn from all the documentation

Also "VCS"?

Normal git users don't go around saying "VCS" no more.. it's like VHS :)

We put "VCS" in a bunch of navigation labels, links and titles.. it's quite bad, I think people won't get what an entire core section of our feature list is about.

[ericholscher]

@benjaoming What would replace it? Just saying git?

[benjaoming]

In some cases "git" is enough, some cases it can work with "git platform". I'm not convinced that "git host", "git provider", "git system" or "git service" sound good.

[agjohnson]

I'll bump this to Q1 assuming we're doing a soft deprecation on providers to start. That seems achievable

[benjaoming]

@agjohnson

Could a deprecation look like this?

1. Remove mentioning of bzr, hg and svn from documentation (or archiving them in a legacy section)
2. Once our new Policy for Supported Tools is added, then update it: Docs: policy for supported tools and dependencies #7859
3. Remove support of bzr, hg and svn from import wizard
4. Notify remaining projects
5. Finally remove build support, API support and clean up code + API docs

I am asking because I'm interested in how soon we can start to rename and simplify some of the current VCS articles, since they are going through some processing over the next weeks.

[agjohnson]

I think what we're talking about above is not doing 4 and 5. Doing all of the work to notify projects and break their usage will be a fair bit of work, and might be overall negative value too.

I know that having the VCS code around is still a bit of a liability. It would be great if we could version our build backend API in some fashion and disregard this code going forward. Perhaps if that is a possibility that would be the point in time to remove the code.

[benjaoming]

@agjohnson

Sounds good - do you have any objections about moving forwards with the first item during the coming weeks? It's mostly about a move towards saying "git" rather than "VCS". Regarding actual contents, we don't have much more than this VCS Support Matrix to remove: https://docs.readthedocs.io/en/stable/versions.html#version-control-support-matrix

[agjohnson]

Next up, we need to contact the users of Tryton, etc and get some feedback.

[humitos]

Here is the draft email that I wrote some time ago. We can use it as a starting point: https://hackmd.io/ZiEI9rbTSI651i71pPyxbw

[ericholscher]

I updated the email to ask for feedback about the change, instead of announcing the change. I think we could send this out.

[humitos]

I can send the email with that content this week probably, if we are 👍🏼 .

[ericholscher]

Sounds good. We should likely only send it to active projects using non-git VCS 👍

[humitos]

I sent the email:

• Community: 26 users / 290 projects
• Commercial: 7 users / 1 project

Let's see what's the feedback we receive from this.

[ericholscher]

Got 3 annoyed users, which seems like a small number in the scheme of things..

[AlbertMietus]

I don't understand this issue ...
Yes, I know, I'm one of those "non-git" users; but that is only partly the point
BTW never got an email on this topic ... So the numbers above are wrong -- I probably am not the only one
Besides, It's kind of misleading to survey git on a git-fan website!

Anyhow, when we can vote: I would VOTE NO.
Not only because I have thought about which VCS I prefer ("not-git"), and I like to have the freedom to choose what is best for me/my projects.
I think we, at least most of us, support "open source". Open! That is the liberty to choose. Which IMHO opinion includes which VCS?

I can (kind of) understand that we sometimes need to remove existing functionality.

• For example, when 'we' have to pay to support a VCS.
• Or, when it depends on non-maintained, bad, unsecured, ... 3rd party software
• Maybe even when supporting "less used" parts is very labour-intensive.
  (Although, the latter is typical/often a symptom of a bad design)

When counting the numbers, roughly 2.5% of all projects use "non-git". One can argue, that is a minority, but does that matter?

ReadTheDocs is about "docs". Not about "the best VCS". As I stated, I don't understand the issue. IMHO there is no valid reason to exclude "others".

I don't like to believe this initiative is a kind of "git wants to rule the world by ignoring all others". Plz, do not make it look like that (asking for support on a git-site; ignore initial, old users, etc).

[ericholscher]

@AlbertMietus What is the project you have on RTD? I'd like to understand why we didn't email you.

[agjohnson]

A couple notes on next steps:

• Dates on brown outs and final cut off
• Blog posts and docs, email updates

[AlbertMietus]

@ericholscher

What is the project you have on RTD? I'd like to understand why we didn't email you.

Currently, Only a few, small "doc only" ones.

See e.g.

https://readthedocs.org/projects/docideas/

[humitos]

I started writing a blog post to communicate our decision. It also has some potential workaround ideas for people that want to migrate their repositories to Git or keep using their VCS to build the docs on Read the Docs. I hope that helps.

[SirNate0]

https://gitthedocs.com/ domain is available and not that pricey.