Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub.
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.
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:
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.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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:
...
Subversion is only used by dinosaurs, unwilling to adapt.
This statement does not sound like a welcoming community waits at Github.
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.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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.
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:
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
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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.
Last edit: Günter Milde 2022-06-01
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
On Wed, 2021-10-20 at 18:07 +0000, engelbert gruber via Docutils-develop wrote:
hei
sorry I must have missed Pradyun's question
maybe it was on sphinx-doc ? https://github.com/live-clones/docutils/tree/master/docutils should be
uptodate
as far as I understand, github maintains this repo, doesnt it ?
No, this is an independent mirror of the repo maintained by a third-party. It
doesn't seem particularly wise to suggest contributors rely on a non-
authoritative mirror, or to rely on a volunteer with no apparent vested interest
in the project (compared to the maintainers) to maintain the mirror long-term.
Pointing to third-party clones and suggesting people use that also ignores the
other advantages that the main project could gain by using a better forge, not
least a vastly improved bug reporting/tracking system. It also doesn't eliminate
the aforementioned svn-to-git weirdness.
As suggested previously, I think the minimum changes that many external
contributors would like to see is git used as the underlying VCS, and an issue
tracker that exists somewhere other than Sourceforge. I'm not sure how I could
personally advocate for this any better than anyone else has, so I'll say no
more.
Stephen
Last edit: Günter Milde 2022-06-01
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
No, this is an independent mirror of the repo maintained by a third-party.
It doesn't seem particularly wise to suggest contributors rely on a
non-authoritative mirror, or to rely on a volunteer with no apparent vested
interest in the project (compared to the maintainers) to maintain the
mirror long-term.
sorry my bad
Last edit: Günter Milde 2022-06-01
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thank you for your input. You have been heard; no need to keep posting
about this. Please be patient. There will be follow-ups on this (and other
things) before too long.
David Goodger
👍
2
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thanks! I think a contributor using GitHub as part of their workflow is perhaps being yet-another-indicator that docutils will get more contributors if it migrates to GitHub. :)
I appreciate that everyone's got limited time and I didn't intend to be pushy.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I would just like to say I use Git a lot and my only reservations are 1)
GitHub is often blocked by companies / agencies because of the sites ties
to China. I would suggest long term to use GitLab.
Secondly, Forking isn’t so much a problem if branching isn’t allowed but
branching seems more natural. The main thing I worry about is someone
activating a pull request which is against the core principles of Docutils
and, when the suggested changes are rejected, goes and creates their own
Docutils on GitLab or GitHub and submits it to pypi and users don’t know
which one is legit. That’s my only other concern. Beyond that, I have no
issue with Git but ask you show some patience with David as he’s only just
come back to the project in force recently.
Jeffrey
Last edit: Günter Milde 2022-06-01
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
GitHub is often blocked by companies / agencies because of the sites ties to China
GitHub is owned by Microsoft, so I’m a bit confused by your insertion it has ties to China.
A company could choose to block any site at any time, so I don’t think this should be a consideration.
Also https://github.com/pythonhttps://github.com/python itself is on GitHub and most core Python tools, so if your company does block GitHub, you are going to find it difficult to do any Python development.
when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub.
This is the nature of open source programming, and already easily possible.
Moreover, it should be encouraged for people to create forks, if that’s what they require for their own use case.
There can still only be one package under the exact “docutils” name in PyPI.
If open source developers want to “gate-keep” their code, then I would suggest they should not be making their code open source, or change the licensing.
Last edit: Günter Milde 2022-06-01
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thanks for the response! This is all good to know.
I asked if there's any updates, primarily because I'm interested in helping out with the migration and willing to do the work. However, it still isn't clear to me that:
(1) the maintainers want to migrate.
(2) what the concerns for doing a migration.
(3) whether my helping hand would be welcome.
I guess it being a TODO item indicates that there's interest in moving to git. That's great, but not what I'm asking (and also not the original scope of this issue).
I'd like one of the maintainers to explicitly state whether you're interested in a migration to GitHub. Further, I'd appreciate if a maintainer could elaborate on (2) and (3). It's fine if the answer is "no" or "I don't know" -- even knowing that will be better.
At this point, if I don't get a clear-enough response for these in a reasonable amount of time, I'm going to step away and focus my energy elsewhere.
Last edit: Pradyun Gedam 2022-01-22
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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,
👍
1
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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.
On Fri, Jan 21, 2022 at 02:39 Juan Luis Cano Rodríguez juanluis@readthedocs.org<mailto:juanluis@readthedocs.org> 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
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
(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.
Last edit: Pradyun Gedam 2022-05-31
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
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:
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:
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.
No need to know any SVN, we accept mailed/uploaded patches against a Git
checkout.
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.
...
This statement does not sound like a welcoming community waits at Github.
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:
so i figure everyone can clone and start sending prs to me/the docutils-dev
list, init ?
cheers
Last edit: Günter Milde 2022-06-01
Hi,
On Mon, Oct 18, 2021 at 11:11 PM engelbert gruber via Docutils-develop
docutils-develop@lists.sourceforge.net wrote:
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 svnis 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:
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:
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.
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.
Last edit: Günter Milde 2022-06-01
hei
sorry I must have missed Pradyun's question
maybe it was on sphinx-doc ?
https://github.com/live-clones/docutils/tree/master/docutils should be
uptodate
as far as I understand, github maintains this repo, doesnt it ?
cheers
Last edit: Günter Milde 2022-06-01
On Wed, 2021-10-20 at 18:07 +0000, engelbert gruber via Docutils-develop wrote:
Pointing to third-party clones and suggesting people use that also ignores the
other advantages that the main project could gain by using a better forge, not
least a vastly improved bug reporting/tracking system. It also doesn't eliminate
the aforementioned svn-to-git weirdness.
As suggested previously, I think the minimum changes that many external
contributors would like to see is git used as the underlying VCS, and an issue
tracker that exists somewhere other than Sourceforge. I'm not sure how I could
personally advocate for this any better than anyone else has, so I'll say no
more.
Stephen
Last edit: Günter Milde 2022-06-01
On Thu, 21 Oct 2021 at 13:30, Stephen Finucane stephen@that.guru wrote:
sorry my bad
Last edit: Günter Milde 2022-06-01
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):
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.
To everyone who commented on this,
Thank you for your input. You have been heard; no need to keep posting
about this. Please be patient. There will be follow-ups on this (and other
things) before too long.
David Goodger
Hiya folks! Any updates on this? It's been two months without activity on this.
hei
Adam cloned the live-clone on github and started contributing .
Günter is busy being cautious not to break docutils compatibility and still incorporate changes.
I am slow
Thanks! I think a contributor using GitHub as part of their workflow is perhaps being yet-another-indicator that docutils will get more contributors if it migrates to GitHub. :)
I appreciate that everyone's got limited time and I didn't intend to be pushy.
The issue not forgotten. You may have a look at
https://docutils.sourceforge.io/docs/dev/todo.html#repository
for some thoughts (and at the version history at
https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt
to monitor the (admittedly slow) progress).
I would just like to say I use Git a lot and my only reservations are 1)
GitHub is often blocked by companies / agencies because of the sites ties
to China. I would suggest long term to use GitLab.
Secondly, Forking isn’t so much a problem if branching isn’t allowed but
branching seems more natural. The main thing I worry about is someone
activating a pull request which is against the core principles of Docutils
and, when the suggested changes are rejected, goes and creates their own
Docutils on GitLab or GitHub and submits it to pypi and users don’t know
which one is legit. That’s my only other concern. Beyond that, I have no
issue with Git but ask you show some patience with David as he’s only just
come back to the project in force recently.
Jeffrey
Last edit: Günter Milde 2022-06-01
GitHub is owned by Microsoft, so I’m a bit confused by your insertion it has ties to China.
A company could choose to block any site at any time, so I don’t think this should be a consideration.
Also https://github.com/python https://github.com/python itself is on GitHub and most core Python tools, so if your company does block GitHub, you are going to find it difficult to do any Python development.
This is the nature of open source programming, and already easily possible.
Moreover, it should be encouraged for people to create forks, if that’s what they require for their own use case.
There can still only be one package under the exact “docutils” name in PyPI.
If open source developers want to “gate-keep” their code, then I would suggest they should not be making their code open source, or change the licensing.
Last edit: Günter Milde 2022-06-01
Thanks for the response! This is all good to know.
I asked if there's any updates, primarily because I'm interested in helping out with the migration and willing to do the work. However, it still isn't clear to me that:
(1) the maintainers want to migrate.
(2) what the concerns for doing a migration.
(3) whether my helping hand would be welcome.
I guess it being a TODO item indicates that there's interest in moving to git. That's great, but not what I'm asking (and also not the original scope of this issue).
I'd like one of the maintainers to explicitly state whether you're interested in a migration to GitHub. Further, I'd appreciate if a maintainer could elaborate on (2) and (3). It's fine if the answer is "no" or "I don't know" -- even knowing that will be better.
At this point, if I don't get a clear-enough response for these in a reasonable amount of time, I'm going to step away and focus my energy elsewhere.
Last edit: Pradyun Gedam 2022-01-22
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,
I certainly do not mind you popping in
thanks for the hints
Last edit: Günter Milde 2022-06-01
Again you haven’t supplied any reference to support your claims.
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.org<mailto:juanluis@readthedocs.org> 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
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.
Last edit: Pradyun Gedam 2022-05-31
There is some progress, see the update to
todoin [r9059] ( https://docutils.sourceforge.io/docs/dev/todo.html#repository ).The script is not yet fully finished though, and I don't know who controls
docutils/docutils, we'd want to talk to them too to get a transfer done.A
Related
Commit: [r9059]
Last edit: Adam Turner 2022-05-31