Hi everyone,

Looks like my email response went nowhere, so posting it here again. Apologies if this message arrives twice to folks, it's my first time posting to a Sourceforge feature request.

I have been reading this conversation mostly from the sidelines. I am a big proponent of using GitHub or any other equivalent service for the reasons I'll state below.

However, before going any further, I would like to make an urgent call for civility. Pradyun initial message was very well framed and asked very specific questions in a positive tone, and I think that is the only way to carry this discussion forward.

People seem to have very strong feelings against Sourceforge, which I totally understand. But folks, this is ultimately the maintainers' call, and some of us are doing a very poor job at making our point without engaging in aggressive language or deaf arguments. The "subversion is only used by dinosaurs, unwilling to adapt" line is what finally triggered me, and I ask all the other migration advocates to stop using this language.

Engelbert asked:

is there a difference if you clone from the docutils-mirror on github
to cloning from a docutils master on github ?

And the answer is honestly "no". Cloning the repository is the most trivial operation: it's been 10 years since I last used SVN, but I'm sure I could clone the original source from SF in under 10 minutes. And cloning from one git mirror or the other is the same, as long as they are up to date of course.

However, what I think folks would like to have is a better means to socially interacting with the project and contributing back to the project, which goes far beyond cloning the source. In this regard, the advantages of either GitHub, GitLab, or other non-profit alternatives like Codeberg (based on Gitea and maintained by a German non-profit) are:

Modern web interface for issue and feature request tracking
Social features (ping users by nickname, cross-reference issues from other projects like Sphinx or CPython)
Polished web interfaces for code review, which allow reviewing patches line by line in a very detailed way
Seamless integration with Continuous Integration services, which can help monitor test coverage and help contributors see if their patches are correct

These are only my two cents, but they hardly add anything new on top of what anyone else can say about these modern platforms. I think the migration proponents have very clear arguments in favor of migrating that have been stated many times. However, the docutils maintainers are probably sick of seeing this conversation popping up over and over again, sometimes with people voicing their arguments in a somewhat disrespectful fashion. If I were them, I would be very annoyed as well.

What I would really love then is for any of the maintainers to kindly answer Pradyun's questions above, so we can have a better idea of what's missing, and if it's worth keeping this discussion alive.

in order to upstream your change, you will still need to meddle with
mailing lists + source forge + svn.

No need to know any SVN, we accept mailed/uploaded patches against a Git
checkout.

Using the docutils-mirror is not even a possibility, because it is severely
outdated:

Unfortunately, there are a lot of outdated/defunct mirrors and forks, indeed.

See https://docutils.sourceforge.io/docs/dev/repository.html for links to
up-to-date mirrors.

For me personally, the reason I think the current sourceforge project is
unwelcoming an github/gitlab is superior can be summed up into 3 points:

...

1. Subversion is only used by dinosaurs, unwilling to adapt.

This statement does not sound like a welcoming community waits at Github.

1. Allowing only mail for sending patches raises the bar for sending
   patches/improvements.

It might work for the kernel, but that project is of a total other scale
and has a different target audience.
Github/gitlab allows users to easily fork a project, make changes,
commit, push and send their changes upstream.
Mailing lists might work, but you lose a certain audience.

Docutils is in some aspects a core project, too: it provides a base for
rST processing frameworks, inner consistency is important, "featuritis"
and hacky solutions are a threat.

On Tue, 19 Oct 2021 at 02:34, Maarten pacha2087@users.sourceforge.net
wrote:

It all comes down to entry barrier.
Even when using a docutils mirror on github to fetch the most up-to-date
master,
in order to upstream your change, you will still need to meddle with
mailing lists + source forge + svn.

Using the docutils-mirror is not even a possibility, because it is severely
outdated:
https://github.c https://github.com/docutils-mirror/docutils
om/docutils-mirror/docutils https://github.com/docutils-mirror/docutils
(last commit was 6+ years ago)

sorry i was talking about github live clone
https://github.com/live-clones/docutils/tree/master/docutils
(thought everyone knew about github making live clones, at least on github)

so i figure everyone can clone and start sending prs to me/the docutils-dev
list, init ?

cheers

Hi,

On Mon, Oct 18, 2021 at 11:11 PM engelbert gruber via Docutils-develop
docutils-develop@lists.sourceforge.net wrote:

what is so hard about the question: i really would like to know: so i
repeat it

is there a difference if you clone from the docutils-mirror on github
to cloning from a docutils master on github ?

thanks for your kindness

I would still argue, as I did above, that it only really becomes clear
why Git and Github are very much better for this workflow, once
you've used them for a while. And to repeat that this was indeed a
common discussion around 2010 or so when many projects were switching,
and some developers who were used to SVN, and who had not used Git,
thought that there was no advantage, and didn't accept the
explanations. It always boiled down to 'Try it, honestly, it's much
better'.

But - you're right - it's good to be concrete. So, this is just to
show you what I would do, exactly, if I wanted to submit a
patch to Sphinx, or Numpy or ...

These are commands from the shell. In this case, I'm using Powershell on
Windows, but bash on macOS or Linux is the same:

Clone the main repository

hub clone sphinx-doc/sphinx

Make my own fork to store my feature branches.

cd sphinx
hub fork

Start work on my feature branch

git checkout -b my-feature

Do some commits. Perhaps rebasing a few times to clear up my history.

Push the resulting code up to my own repository on Github.

git push matthew-brett my-feature -u

Make a pull-request on Github

hub pull-request

Now the maintainer and the author have a nice web interface on which to
review the diff, make line-by-line comments, make suggestions for automatic
changes, mark comments as resolved and so on. This is a very nice and pleasant
workflow for the contributor. I personally also find it much nicer as a
reviewer.

All this is very quick - each step is, at longest, a few seconds. I'm using
the nice Hub utility here, because that is what I'm used to, but if not, the
equivalent steps in the web interface are very obvious and familiar.

Now, here's what that would look like with the docutils mirror.

Of course,it starts off the same:

hub clone docutils-mirror/docutils
cd docutils
hub fork

Now I have a serious problem, because, as Maarten points out, this repository
is very, very out of date. What to do? Now I have to go and look up how to
update a Git repository from SVN. First hit is here:

https://stackoverflow.com/questions/10886784/updating-a-git-mirror-of-an-svn-repository

I tried the instructions there, just now, but they didn't work for me. And, in
general, git svn is a pretty complex tool that is really not for beginners.

OK - but let's say that someone is kindly pushing up every commit to the Github
repo, and I don't have to do that.

Next I do the equivalent work to the work I did above.

Start work on my feature branch

git checkout -b my-feature

Do some commits. Perhaps rebasing a few times to clear up my history.

Now, because I use the standard Git push and Github interface for
everything, I don't
remember how to make commits into patches, and I look that up.

It turns out I need:

git format-patch origin/master

This leaves me with one patch per commit. I go to my mail client, attach
those patch files to the email, write the email, and send it.

So the main points are:

a) The Git-SVN bridge is very clunky, and it's unreasonable to expect users to
be able to update it.
b) Very few developers now learn SVN - and developers that are used to Git,
will find SVN a significant barrier. That's true of me too, and, as I say,
unlike most younger developers, I used SVN actively for many years.
c) Even if the Git-SVN bridge was always up to date, the workflow of generating
patches and emailing them is unfamiliar, and your developers are very likely to
need to look up how to do this. It's not that hard, but it's not as easy as
the Github interface, so this will cause some further uncertainty and
discomfort.

Basically, almost all current developers are very familiar with, and largely
happy with, the Git / Github / Gitlab etc workflow. The SVN / patches via
email workflow will be unfamiliar, and as well as unfamiliar, rather
inconvenient. And it will be difficult for your developers to understand why
you prefer the SVN / email patches workflow.

The questions then are - what is the up-side that corresponds to these
downsides?
Do you see Docutils staying with SVN / Sourceforge for a long time? At what
point will using SVN and Sourceforge be too much of a burden for other
developers? In another
year? Or two? And what is the benefit of waiting to switch?

Cheers,

Matthew

Dear docutils developers, I'm bringing this up one final time because docutils is a very important project to the python ecosystem and because I care a lot about it's documentation infrastructure. I strongly believe that migrating would make work for maintainers and people wanting to contribute easier. (You don't have to follow that opinion, but it's the motivation why people bring this up again and again).

To resolve the issue once and for all, I'd like to draw the attention back to the simple question by @Pradyon Gedam:

Is there any interest amongst the maintainers/existing contributors to move away from Sourceforge?

If there is no interest, please state this very clearly and close the topic. Otherwise people will bring up the topic again and again. And to be clear: No interest is a legitimate choice.
Ideally, accompany the statement with a short explanation so that people can understand your reasons. All reasons for the choice are legitimate (from sourceforge is good enough for us, over we are not interested in more community engagement/cannot handle the associated work up to we don't have the time to migrate; or anything else).

If moving is something you might consider, but there are still some doubts or practical problems, I'm sure we'll find enough people willing to help in various ways; be it answering questions, showing how to work with other platforms, supporting the actual migration, possibly up to organizing financial sponsorhip if that should be a limiting factor. We have a strong community and can achieve much if there is interest!

I’d note we have already been through this discussion, it seems at least once a year lol. With https://github.com/chrisjsewell/docutils I have already shown that it is really quite trivial to migrate. I get the strong impression though that the maintainers are against moving. This is absolutely their prerogative, but yeh I think the clear benefits of git vs svn are just not in question at this point

Cheers,
Chris

On Tue, 2021-10-19 at 07:04 +0000, Juan Luis Cano Rodríguez wrote:

Hi everyone,

I have been reading this conversation mostly from the sidelines. I am a big
proponent of using GitHub or any other equivalent service for the reasons I'll
state below.

However, before going any further, I would like to make an urgent call for
civility. Pradyun initial message was very well framed and asked very specific
questions in a positive tone, and I think that is the only way to carry this
discussion forward.

People seem to have very strong feelings against Sourceforge, which I totally
understand. But folks, this is ultimately the maintainers' call, and some of
us are doing a very poor job at making our point without engaging in
aggressive language or deaf arguments. The "subversion is only used by
dinosaurs, unwilling to adapt" line is what finally triggered me, and I ask
all the other migration advocates to stop using this language.

Thank you, Juan Luis. I'm glad it's not just me that was disappointed to see
these kinds of comments appearing in a previously interesting thread. Let's
avoid this kind of rhetoric.

Engelbert asked:

is there a difference if you clone from the docutils-mirror on github
to cloning from a docutils master on github ?

And the answer is honestly "no". Cloning the repository is the most trivial
operation: it's been 10 years since I last used SVN, but I'm sure I could
clone the original source from SF in under 10 minutes. And cloning from one
git mirror or the other is the same, as long as they are up to date of course.

However, what I think folks would like to have is a better means to socially
interacting with the project and contributing back to the project, which
goes far beyond cloning the source. In this regard, the advantages of either
GitHub, GitLab, or other non-profit alternatives like Codeberg (based on Gitea
and maintained by a German non-profit) are:

• Modern web interface for issue and feature request tracking
• Social features (ping users by nickname, cross-reference issues from other
  projects like Sphinx or CPython)
• Polished web interfaces for code review, which allow reviewing patches line
  by line in a very detailed way
• Seamless integration with Continuous Integration services, which can help
  monitor test coverage and help contributors see if their patches are correct

These are only my two cents, but they hardly add anything new on top of what
anyone else can say about these modern platforms. I think the migration
proponents have very clear arguments in favor of migrating that have been
stated many times. However, the docutils maintainers are probably sick of
seeing this conversation popping up over and over again, sometimes with people
voicing their arguments in a somewhat disrespectful fashion. If I were them, I
would be very annoyed as well.

I have to agree with all of the above. However, I will also note that this need
not be an all-or-nothing thing. Use of GitHub's (or GitLab's) for a repo and
issue tracker does not mean insisting on their contribution workflow. It is
still quite possible to keep accepting patches via mailing list. The kernel does
this, as do many other projects (Open vSwitch and DPDK jump to mind). We also
don't have to use GitHub or GitLab: there are a variety of other forges, such
as sourcehut.org (note: I have not used this myself) which we could use.
Fundamentally though, I think many of us would love to at least see docutils
move its chosen VCS from SVN to Git, in order to avoid reliance on the svn-to-
git crutch and make things less "weird" for outside contributors, and to move
issue trackers from sourceforge, given the website's difficult navigation and
poor reputation owing to bundled malware and project hijackings (caveat: these
issues have been mostly resolved since, but once bitten...). If we could even
come to some agreement on tackling these two topics, I think we'd be making a
great start.

Cheers,
Stephen

PS: In relation to the comment previously about the poor quality of some
submissions, I have submitted a large number of patches some time back to add
native Python 3 support to docutils, ending our reliance on the 2to3 tooling
(which, it's worth noting, has since been removed from setuptools). I consider
this series to have been high quality and pretty extensive. I would be
interested in contributing more to docutils (I have an rst2txt project that I
think would make a good addition to the core project) but the poor tooling
provides good reason to spend my limited time elsewhere.

I don't know why this needs to be stated explicitly -- uhm... Do not be disrespectful to the maintainers of the project, or their choice of platform. They're choosing what works for them -- if it doesn't work for you, deal with it. By being disrespectful toward the maintainers, you're not helping anyone.

Pardon the metaphor: You don't get to show up to a stranger's house, start by criticising them and their choice of furniture, and then expect that they'd still be willing be to do you a favour.

To the docutils maintainers:

As I'm sure you're aware, docutils is a critical tool for Python's documentation ecosystem. I empathize with the fact that migrations are painful, that it will require you to gain familiarity with a new platform, that the benefits seem unclear/non-existent to you and that you've have some bad interactions around this topic.

I'll reiterate my offer to help with the migration. As has been mentioned earlier in this thread (as well as from a thread in 2014 on the docutils-develop mailing list), the migration is feasible and reasonably straightforward.

I hope that you haven't brushed aside all the positive things about GitHub that have been mentioned such as the reduced overhead in maintainer workflows with automated testing + linting on every commit / pull request (i.e. patch submissions), the simpler contribution workflow, significantly better discoverability, a much more modern user interface and more.

I hope you've noticed that multiple folks have talked how SourceForge is "very outdated", and how it has a "higher barrier to entry". I hope you understand that leads to fewer contributions and lower quality contributions.

I hope you've noticed that the list of folks speaking in favour of migrating to GitHub and been a moderating voice in this discussion is much longer than that of folks who have been disrespectful.

I hope you won't use a few bad apples, to say that the broader group is disrespectful / unwelcoming.

I hope that you've noticed that nearly everyone has been very respectful and provided detailed responses to your often-terse responses.

I hope that you don't think that "mean people" is representative of the community engaging with you here. We've had many folks with strong feelings have show up to say things here and a very small subset of them have been disrespectful, and other have called them out on it.

I want to point out that the list of folks speaking in favour of migrating includes maintainers from Python Packaging Authority (https://www.pypa.io/en/latest/), ReadTheDocs (https://readthedocs.org/), Executable Books (https://executablebooks.org/en/latest/), Ansible (https://www.ansible.com/), staff from various universities, contributors to Sphinx (https://www.sphinx-doc.org/en/master/) and... I'm still missing a few people whose credentials I don't know/couldn't look up. The list of folks who have said they prefer GitHub to SourceForge is even longer, and includes a Sphinx maintainer.

I'd argue that all of these are folks who are a part of the docutils' existing community and who would be significantly more likely to contribute to the project in a greater capacity, if docutils were on a platform that they were more comfortable using.

Finally, I'll repeat my question from my first post here (which a few folks have mentioned, and other have mentioned that they didn't notice):

If folks wish to stick with Sourceforge and SVN, on principle of avoiding git because it uses hashes / proprietary software like GitHub / Microsoft owned stuff / "centralisation of open source" / something along those lines, could someone explicitly state that? (These are all things I've read on the mailing list archives for this project, but they're from a decent amount of time ago -- people are definitely entitled to changing their opinions as time passes).

Having clarity on what your concerns are would be great.

--
Pradyun Gedam

I help maintain critical open source digital infrastructure for Python like pip, PyPI, TOML and more.

Hello from SourceForge staff, hope you don't mind us popping in with a few suggestions.

SourceForge projects support git including merge requests. So one option that I don't think has been mentioned yet would be converting from SVN to Git within SourceForge. We don't have a magical one-click button to do that, but a Git repo can be added to an existing project. Then standard svn=>git migration tools can be used, and push the git repo up.

If you decide to migrate development elsewhere, that's fine too. You can add an "External Link" item directly into the SourceForge project menu if you wish to have links to other sites, but still keep a presence on SourceForge with releases, news, mailing list archives, etc.

Best regards,

Again you haven’t supplied any reference to support your claims.

you have not given a single reason why not GitLab

You wouldn’t be able to have integrated referencing (in issues and PRs) between docutils and sphinx, readthedocs, myst, and the majority of the python ecosystem that are on GitHub. Also first-class integration with VS Code, the most used development tool,...

Anyhow I’m not going to continue a flame war. I just wanted to make sure that your views wasn’t the only one represented here.

Cheers,
Chris

On 23 Jan 2022, at 12:49, Jeffrey C. Jacobs timehorse@starship.python.net wrote:



On Fri, Jan 21, 2022 at 02:39 Juan Luis Cano Rodríguez juanluis@readthedocs.orgamp#106;amp#117;amp#97;amp#110;amp#108;amp#117;amp#105;amp#115;amp#64;amp#114;amp#101;amp#97;amp#100;amp#116;amp#104;amp#101;amp#100;amp#111;amp#99;amp#115;amp#46;amp#111;amp#114;amp#103; wrote:
GitHub is an American company, and GitLab is hosted on Google Cloud Platform, an American company, and SourceForge is owned by Slashdot Media, an American company. American companies are subject to American laws, in particular regarding trade restrictions and sanctions to other countries[1].

Nonetheless it is blocked by US companies and federal agencies and the reason stated is ties to China. I’m thinking fighting the US government on its opinions of this is a battle of logic you’re not going to win. GitHub is a barrier, GitLab is not. I vote GitLab.

Also, defending GitHub you have not given a single reason why not GitLab, so, if they are equivalent, they why not GitLab?

Personally, I don’t like leaving the office and reading GitHub on my phone just to do something.

Jeffrey

"Scan not a friend with a microscopic glass; you know his faults so let his foibles pass." -- Victorian Proverb, likely Sir Frank Crisp, 1st Baronet of Bungay

"Dans le silence on ne sait pas, il faut continuer, je ne peux pas continuer, je vais continuer." -- L'Innommable, Samuel Beckett

"and thus the whirligig of time brings in his revenges" -- The Clown
from 'Twelfth Night' v, , Act 5, Scene 1 by William Shakespeare

"Le mieux est l'ennemi du bien." -- François-Marie Arouet (Voltare), La Bégueule (1772)

~,-;` The TimeHorse

(1) the maintainers want to migrate.
(2) what the concerns for doing a migration.
(3) whether my helping hand would be welcome.

Given the lack of responses here, I'm going to assume that the answers here are (1) no, (2) that the maintainers would have to learn something new and (3) no.

Thanks for indulging me I guess? I say that but I'll note that I don't think I got a clear answer to most (if not all) of the direct questions I asked here.

I'm gonna be fairly sad that such a foundational project for Python's documentation ecosystem is going to stay on a platform that makes it nearly impossible for me to write a comment over my phone on their website, in 2022 and that the maintainers don't see that as a problematic aspect of the platform.