Bug 1382405
Summary: | sphinx-quickstart not working. Alternatives is not the right solution | ||
---|---|---|---|
Product: | [Fedora] Fedora | Reporter: | Toshio Ernie Kuratomi <a.badger> |
Component: | python-sphinx | Assignee: | Michel Lind <michel> |
Status: | CLOSED EOL | QA Contact: | Fedora Extras Quality Assurance <extras-qa> |
Severity: | unspecified | Docs Contact: | |
Priority: | unspecified | ||
Version: | 25 | CC: | aviso, michel |
Target Milestone: | --- | Keywords: | Reopened |
Target Release: | --- | ||
Hardware: | Unspecified | ||
OS: | Unspecified | ||
Whiteboard: | |||
Fixed In Version: | python-sphinx-1.4.8-1.fc25 python-sphinx-1.4.8-1.fc24 python-sphinx-1.4.8-2.fc24 | Doc Type: | If docs needed, set a value |
Doc Text: | Story Points: | --- | |
Clone Of: | Environment: | ||
Last Closed: | 2017-12-12 11:06:01 UTC | Type: | Bug |
Regression: | --- | Mount Type: | --- |
Documentation: | --- | CRM: | |
Verified Versions: | Category: | --- | |
oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
Cloudforms Team: | --- | Target Upstream Version: | |
Embargoed: |
Description
Toshio Ernie Kuratomi
2016-10-06 14:59:51 UTC
Upstream did not see a problem since Sphinx for Python 2 and Python 3 share a codebase and are functionally equivalent. Alternatives was the best solution we could come up with. The user is free to set their own aliases or call the version-specific commands themselves. If you'd like to implement something else, send the diff and we'll try it out. As far as your issues. I'm not sure why you're seeing them. The old files should be removed, but I'll add something to the scripts to remove the files if they are found and are not symlinks. python-sphinx-1.4.8-1.fc25 has been pushed to the Fedora 25 testing repository. If problems still persist, please make note of it in this bug report. See https://fedoraproject.org/wiki/QA:Updates_Testing for instructions on how to install test updates. You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2016-388fa860a3 python-sphinx-1.4.8-1.fc24 has been pushed to the Fedora 24 testing repository. If problems still persist, please make note of it in this bug report. See https://fedoraproject.org/wiki/QA:Updates_Testing for instructions on how to install test updates. You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2016-ece47fcde8 Avram Sphinx is not functionally equivalent between the Python2 and Python3 versions. Especially when autodoc comes into the picture. Ugh. You pushed the alternatives change back to fedora 24 too :-( Yes, fixed the issue you reported when updating from old versions of Sphinx. The current solution allows a sane and configurable system default, and allows a user to determine their preference through aliases or direct calls. Upstream does not distinguish between versioned commands and they are compiled from the same code. The current solution addresses a number of issues we had in the past. If you do not like the way the RPM is implemented, submit a patch with an alternate solution. It does not address the issues that were raised before. Reread those issues and you'll see that we talkked it over and the way it was left was that only upstream could fix those issues. The issues still remain even with your mistaken use of alternatives. Upstream will not fix it because they don't see an issue. The conversation you are referring to was only a small part of the discussions. Again, you can criticize my approach as much as you want, but if you want a different solution, do the work. Either create a pull request for upstream or create a spec file. But complaining without contributing is doing no one any good. What you've done to the package is not compliant with the guidelines which restrict when alternatives should be used. So just getting rid of alternatives leaves us in a better place than where we are now. I am working on an update that uses environment-modules instead of alternatives but it was late at night and there's no examples of how to remove alternatives from a package so I have to be careful not to break the package in the process of removing it... Would be so much better if people just read the guidelines and realized that they should not use it in the first place. Where's the upstream ticket where they don't understand the issue? python-sphinx-1.4.8-1.fc25 has been pushed to the Fedora 25 stable repository. If problems still persist, please make note of it in this bug report. python-sphinx-1.4.8-1.fc24 has been pushed to the Fedora 24 stable repository. If problems still persist, please make note of it in this bug report. Sphinx still makes use of alternatives. Re-opening so I remember to fix it. Avram, do you have the upstream ticket? I was still unable to find it. Not sure there was an issue. There was something on the mailing lists and some private discussion, but having trouble finding it. You can always create a new issue. Couldn't find anything by searching https://groups.google.com/forum/#!searchin/sphinx-users/ ... Do you have some search terms I could use to find the thread? python-sphinx-1.4.8-2.fc24 has been submitted as an update to Fedora 24. https://bodhi.fedoraproject.org/updates/FEDORA-2016-cfda867334 python-sphinx-1.4.9-2.fc25 has been submitted as an update to Fedora 25. https://bodhi.fedoraproject.org/updates/FEDORA-2016-db30d55c10 Okay, fix submitted. Please test. I've run a few tests on fedora 25 but there's a large matrix to test for various permutations of previous ppackage installed, previous package not installed, python3 but not python2 package installed and vice versa. Since this is now using environment modules rather than alternatives, switching between packages can now be done without root permissions. Use the module swap command to switch between the two packages. For instance:: # Switch to the python2 version module swap python-sphinx/python2-sphinx # Switch back to the python3 version module swap python-sphinx/python3-sphinx python-sphinx-1.4.8-2.fc24 has been pushed to the Fedora 24 testing repository. If problems still persist, please make note of it in this bug report. See https://fedoraproject.org/wiki/QA:Updates_Testing for instructions on how to install test updates. You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2016-cfda867334 python-sphinx-1.4.9-2.fc25 has been pushed to the Fedora 25 testing repository. If problems still persist, please make note of it in this bug report. See https://fedoraproject.org/wiki/QA:Updates_Testing for instructions on how to install test updates. You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2016-db30d55c10 A few thoughts: 1.) This change should only be implemented in Rawhide and not in any released versions since it's a significant change to the current behaviour 2.) Because this is a debated issue, the changes should not have been made in git. You should have created a separate spec and maybe a copr repo 3.) Your comments in the spec file border on discussion. If you think that is necessary, note the Fedora or upstream bug and leave commentary out of the spec 4.) While I see this as providing a slightly better method than aliases to set the user default, it does not seem obvious now how to set the system default, which in my experience is more important (hence the use of alternatives) 5.) Regardless of if environment modules is or is not the correct solution, it is not popular within Fedora packages, so a short man page should be created with an overview of the solution for Sphinx and instructions on how to set both the user and system default version You should revert your changes in git and work on this independent of git until there is a consensus that the solution is sound. It seems our understanding of the issue is different, but I'm open minded to your solution assuming it does not reduce functionality and you implement it prudently. It took you 2.5 months to put a solution together, I'm not sure why you're in such a hurry to get it out. 1) I'm sorry, I'm just following the precedent that you set by pushing the incorrect changes back to Fedora 24. 2) Since alternatives is wrong, why did you push your changes into git? 3) I can do that but since many other people work on packages that aren't involved with this particular package, the spec file has always been the best place for information. Comments exist to inform people of why code that may be unfamiliar with them is there. 4) These programs need to be handled by *the end user*. Therefore changing system defaults is not at all important. If you want to change the system defaults, it is just as easy to do it with environment modules as it is with alternatives. In both cases you have to learn a tool and then modify one (in the case of environment modules) or more (in the case of alternatives) system configurations. 5) I can do that. The traditional location for that sort of documentation is a REAME.fedora file, though. I'll write one of those up. So in summary... I'll write a documentation file, revert fedora 24 back to not being switchable. Fedora 25 I'll leave with alternatives since F25 was released before I could fix it, rawhide I'll switch to the correct way of doing this. I'm going to leave the comments in because that's what comments are for. ignatenkobrain also alerted me to the fact that python2 is still supposed to be the default for unversioned commands so I'll make sure that all of the packages follow that as well. ignatenkobrain also wondered why we're using Lmod instead of environment-modules.. IIRC, enivronment-modules will work just as well... I was going to use Lmod because it has enhanced support for default values but I ended up going for the least common denominator anyways. I'll try to switch that to environment-modules. python-sphinx-1.4.8-2.fc24 has been pushed to the Fedora 24 stable repository. If problems still persist, please make note of it in this bug report. python-sphinx-1.4.8-3.fc24 has been submitted as an update to Fedora 24. https://bodhi.fedoraproject.org/updates/FEDORA-2017-bd6e494a78 python-sphinx-1.4.8-3.fc24 has been pushed to the Fedora 24 testing repository. If problems still persist, please make note of it in this bug report. See https://fedoraproject.org/wiki/QA:Updates_Testing for instructions on how to install test updates. You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2017-bd6e494a78 (In reply to Toshio Ernie Kuratomi from comment #22) > 1) I'm sorry, I'm just following the precedent that you set by pushing the > incorrect changes back to Fedora 24. The precedent was I fixed a 17 month-old bug, discussed it with upstream and on fedora-devel before making any changes. There were no objections to my approach so I proceeded, cautiously. In your case, you created a bug for something you didn't like, changed it in rawhide and the current release despite objections before vetting your solution. > > 2) Since alternatives is wrong, why did you push your changes into git? > Wrong is your opinion. It solved the problem. In my opinion, you broke it. You could have raised objections when the original bug was discussed. > 3) I can do that but since many other people work on packages that aren't > involved with this particular package, the spec file has always been the > best place for information. Comments exist to inform people of why code > that may be unfamiliar with them is there. This is an appropriate comment: - Remove alternatives (bz#1382405) This is not: - Remove alternatives. Alternatives should only be used for a very small number of packages (system daemons which also have a compatible command line interface). Not only is it too long and irrelevant, it's an opinion. > > 4) These programs need to be handled by *the end user*. Therefore changing > system defaults is not at all important. If you want to change the system > defaults, it is just as easy to do it with environment modules as it is with > alternatives. In both cases you have to learn a tool and then modify one > (in the case of environment modules) or more (in the case of alternatives) > system configurations. If it's so easy, why didn't you put it in the readme file you created? I'm not that familiar with environment modules, but it looks like you have to change files or paths to set a system default. While I see merit in using environment modules, you need to remember a few things: A.) This is a community effort. It is important to be cordial and to try to understand why people have done what they have done. Be careful implementing wide-reaching changes, especially when you aren't sure how others may be using something. B.) Many people want to be able to set a system-wide default for Sphinx and don't care about specific user preferences. This is a development tool, so in a large number of cases, if not the majority, it is installed on a single user (possibly multiple account) system or on a dedicated build system. In both these cases, what you care about is the system default. While I can understand why you would care about the user default and using environment modules is a little more elegant than using aliases, it seems your solution has made it more difficult to set the system default. I'm going to reopen the bug, so you can address this. I would still suggest you back out your changes from git and work in copr until they are ready. (In reply to Avram Lubkin from comment #26) > (In reply to Toshio Ernie Kuratomi from comment #22) > > 1) I'm sorry, I'm just following the precedent that you set by pushing the > > incorrect changes back to Fedora 24. > > The precedent was I fixed a 17 month-old bug, discussed it with upstream and > on fedora-devel before making any changes. There were no objections to my > approach so I proceeded, cautiously. In your case, you created a bug for > something you didn't like, changed it in rawhide and the current release > despite objections before vetting your solution. > I'm sorry that no one on the mailing list pointed you at the guidelines which would have told you that your use of alternatives is wrong. Once I realized that you were doing the wrong thing I pointed it out to you here. I'm also not sure why you chose to take action on a problem report where the conclusion was that this was not something that should be fixed in Fedora packaging. That was a good conclusion. Your choice to push changes for that has just made the packaging more complex and the matter worse. > > > > 2) Since alternatives is wrong, why did you push your changes into git? > > > > Wrong is your opinion. It solved the problem. In my opinion, you broke it. > You could have raised objections when the original bug was discussed. > (1) Not my opinion. This is wrong according to the Fedora Packaging Guidelines: https://fedoraproject.org/wiki/Packaging:Alternatives#Recommended_usage (2) I haven't broken it afaict. Although, you haven't fixed the original problem, and in talking with ignatenkobrain, it sounds like this might be added complexity that doesn't buy us anything so it should probably be discarded and the package go back to the pre-alternatives state. (3) I did participate in the original bug report via the linked fpc ticket here: https://fedorahosted.org/fpc/ticket/612#comment:6 thozza updated the bugzilla ticket and it was subsequently closed here: https://bugzilla.redhat.com/show_bug.cgi?id=1321413#c3 I did not expect that someone would push changes to that afterwards otherwise I would have again objected. > > > > > 4) These programs need to be handled by *the end user*. Therefore changing > > system defaults is not at all important. If you want to change the system > > defaults, it is just as easy to do it with environment modules as it is with > > alternatives. In both cases you have to learn a tool and then modify one > > (in the case of environment modules) or more (in the case of alternatives) > > system configurations. > > If it's so easy, why didn't you put it in the readme file you created? I'm > not that familiar with environment modules, but it looks like you have to > change files or paths to set a system default. > I've added the instuctions to the readme. > > While I see merit in using environment modules, you need to remember a few > things: > > A.) This is a community effort. It is important to be cordial and to try to > understand why people have done what they have done. Be careful implementing > wide-reaching changes, especially when you aren't sure how others may be > using something. > Exactly. I have appreciated that you were willing to step in and keep the package synced with the upstream releases so that I didn't have to think about this package much. However, once you pushed changes to the package in a bad attempt to fix a bug that all involved had decided did not need to be fixed in packaging and then told me to fix it rather than cleaning up the mistake and then blocking the fixes that I then add, your help begins to become a burden instead. If you'd listen, ask questions, and learn, I'd be happy to work together to advance your knowledge of how to package but it seems like you only want to focus on what you think your solution achieves rather than seeing the drawbacks, alternatives, and non-issues. > B.) Many people want to be able to set a system-wide default for Sphinx and > don't care about specific user preferences. This is a development tool, so > in a large number of cases, if not the majority, it is installed on a single > user (possibly multiple account) system or on a dedicated build system. In > both these cases, what you care about is the system default. While I can > understand why you would care about the user default and using environment > modules is a little more elegant than using aliases, it seems your solution > has made it more difficult to set the system default. I'm going to reopen > the bug, so you can address this. I would still suggest you back out your > changes from git and work in copr until they are ready. There's several things you should reconsider here. First, you're confusing single user systems with systems that have only a single user. Linux is a multiuser operating system. Fedora is a distribution that embraces that nature. As such, even if an install has only a single user, the system itself has to be able to anticipate and work with multiple users. Second, the user cases you cite do not care about the system default sphinx and can be hindered by it if the only way that they can switch between the versions is a system default. The user developing code and the buildsystem care that they can build their docs. The system default can be a hindrance when neither one have root access. In those cases, alternatives gives them nothing... they have to call a sysadmin to switch the default before they can do their work. As pointed out in the original ticket, the user can do this switching themselves by setting an environment variable: https://fedorahosted.org/fpc/ticket/612#comment:10 The user and buildsystem would run SPHINXBUILD=/usr/bin/sphinx-build-3 make html, for instance. If they need to toggle between the two sphinx-builds, which is the case when some documentation is dependent on the version of python (working on or building different projects that have different requirements, differences between the docs when built for py2 and py3 leading to having to build twice, etc) for different builds, they will set SPHINXBUILD=/usr/bin/sphinx-build-2 make html in one run and SPHINXBUILD=/usr/bin/sphinx-build-3 make html in the second run. Environment-modules also allows this. The user and build system run module swap python-sphinx/python3-sphinx ; make html and then module swap python-sphinx/python2-sphinx ; make html for the next run. environment-modules also let both the user and sysadmin change what sphinx-build refers to outside of the Makefile but that doesn't seem to have been a large desire in the ticket (as the resolution was just to use the environment variable when building). (In reply to Toshio Ernie Kuratomi from comment #27) > (In reply to Avram Lubkin from comment #26) > > (In reply to Toshio Ernie Kuratomi from comment #22) > > > 2) Since alternatives is wrong, why did you push your changes into git? > > > > > > > Wrong is your opinion. It solved the problem. In my opinion, you broke it. > > You could have raised objections when the original bug was discussed. > > > (1) Not my opinion. This is wrong according to the Fedora Packaging > Guidelines: > https://fedoraproject.org/wiki/Packaging:Alternatives#Recommended_usage > (2) I haven't broken it afaict. Although, you haven't fixed the original > problem, and in talking with ignatenkobrain, it sounds like this might be > added complexity that doesn't buy us anything so it should probably be > discarded and the package go back to the pre-alternatives state. > (3) I did participate in the original bug report via the linked fpc ticket > here: https://fedorahosted.org/fpc/ticket/612#comment:6 thozza updated the > bugzilla ticket and it was subsequently closed here: > https://bugzilla.redhat.com/show_bug.cgi?id=1321413#c3 I did not expect that > someone would push changes to that afterwards otherwise I would have again > objected. > You seem to be misinterpreting the guidelines. First it is a recommendation, not a requirement, second, using alternatives for Sphinx is valid according to the guideline recommendations. There is no functional difference between the Python 2 and Python 3 versions of Sphinx, hence why upstream does not put the version in the makefile, nor would it make any sense for distributing documentation source. The only real difference comes from plugin support. While most support Python 2 and 3, some exclusively run on one or the other. > > > 4) These programs need to be handled by *the end user*. Therefore changing > > > system defaults is not at all important. If you want to change the system > > > defaults, it is just as easy to do it with environment modules as it is with > > > alternatives. In both cases you have to learn a tool and then modify one > > > (in the case of environment modules) or more (in the case of alternatives) > > > system configurations. > > > > If it's so easy, why didn't you put it in the readme file you created? I'm > > not that familiar with environment modules, but it looks like you have to > > change files or paths to set a system default. > > > I've added the instuctions to the readme. Your instructions for updating the system default are kludgy. Moreso, this is what alternatives is for. Using environment module for user preference does not conflict with using alternatives for the system default. As such, you should have just added environment modules and left the alternatives intact. > As pointed out in the original ticket, the user can do this switching > themselves by setting an environment variable: > https://fedorahosted.org/fpc/ticket/612#comment:10 > > The user and buildsystem would run SPHINXBUILD=/usr/bin/sphinx-build-3 make > html, for instance. If they need to toggle between the two sphinx-builds, > which is the case when some documentation is dependent on the version of > python (working on or building different projects that have different > requirements, differences between the docs when built for py2 and py3 > leading to having to build twice, etc) for different builds, they will set > SPHINXBUILD=/usr/bin/sphinx-build-2 make html in one run and > SPHINXBUILD=/usr/bin/sphinx-build-3 make html in the second run. > > Environment-modules also allows this. The user and build system run module > swap python-sphinx/python3-sphinx ; make html and then module swap > python-sphinx/python2-sphinx ; make html for the next run. > environment-modules also let both the user and sysadmin change what > sphinx-build refers to outside of the Makefile but that doesn't seem to have > been a large desire in the ticket (as the resolution was just to use the > environment variable when building). I read through all the discussions, started a new one, and reached out to upstream. Point being, I did a lot of reaching out before making changes. Alternatives was then and still is the best solution based on the way I've seen Sphinx used in the wild. You've had a different experience, and that's fine, that's part of the benefit of community efforts, but going in and making changes like you did without properly vetting your solution is both inconsiderate and reckless. This message is a reminder that Fedora 25 is nearing its end of life. Approximately 4 (four) weeks from now Fedora will stop maintaining and issuing updates for Fedora 25. It is Fedora's policy to close all bug reports from releases that are no longer maintained. At that time this bug will be closed as EOL if it remains open with a Fedora 'version' of '25'. Package Maintainer: If you wish for this bug to remain open because you plan to fix it in a currently maintained version, simply change the 'version' to a later Fedora version. Thank you for reporting this issue and we are sorry that we were not able to fix it before Fedora 25 is end of life. If you would still like to see this bug fixed and are able to reproduce it against a later version of Fedora, you are encouraged change the 'version' to a later Fedora version prior this bug is closed as described in the policy above. Although we aim to fix as many bugs as possible during every release's lifetime, sometimes those efforts are overtaken by events. Often a more recent Fedora release includes newer upstream software that fixes bugs or makes them obsolete. Fedora 25 changed to end-of-life (EOL) status on 2017-12-12. Fedora 25 is no longer maintained, which means that it will not receive any further security or bug fix updates. As a result we are closing this bug. If you can reproduce this bug against a currently maintained version of Fedora please feel free to reopen this bug against that version. If you are unable to reopen this bug, please file a new report against the current release. If you experience problems, please add a comment to this bug. Thank you for reporting this bug and we are sorry it could not be fixed. |