macports-guide
macports-guide copied to clipboard
macports
guide: MP Guide maintenance backlog
This PR is a DRAFT and work in progress (WIP)
The Guide provides excellent advice and is one of the main entry points for MacPorts beginners.
However, IMO quite obviously the MP Guide needs QA and more continuity in maintenance to the text of the guide itself.
This PR:
- Provides the Backlog list - ref https://github.com/macports/macports-guide/pull/53#issuecomment-1374804353
- The former commits are found to be misled unfortunately.
However, any consideration and further advice would be highly appreciated.
Backlog:
Improve
IMO the MacPorts Guide could improve from quality assurance. Nevertheless the Guide provides excellent advice.
WIP - This PR and this Comment could become a standing document until further notice, I presume.
This PR might not be fully compatible to but certainly is related to 7.5. Updating Documentation
Amend
Amending missing content at:
New section on 'subport'
AFAIK the Chapter 4. Portfile Development lacks sufficient documentary on the 'subport' excellent opportunities both for new Portfile development and port mainentance, unfortunately.
section 4.7. Portfile Best Practices
- 4.7.2. Don't Overwrite Config Files TODO:
- 4.7.3. Install Docs and Examples TODO:
- 4.7.4. Provide User Messages TODO:
-
4.7.5. Use Variables
TODO: Set variables so changing paths may be done in one place; use them anytime it makes updates simpler:
distname ${name}-src-${version}
section 5.6. Tcl Extensions & Useful Tcl Commands
External program execution
Use only when ....
section 6.1. File Hierarchy
PORTHIER — layout of the ports filesystems Name porthier — layout of the ports filesystems
harmonisation of sections 7.1 & 7.3
section 7.1. Using Trac for Tickets
The MacPorts Project uses a system called Trac to file tickets to report bugs and enhancement requests. Though anyone may search Trac for tickets, you must have a GitHub account in order to login to Trac to create tickets.
ADD: The GitHub pull request method is strongly preferred over submitting Trac tickets.
section 7.3. Contributing to MacPorts
You may contribute new ports and enhancements of any kind to already existing ports using Trac tickets. However, we prefer that you open a pull request on GitHub, in which case no Trac ticket is required.
The GitHub pull request method is strongly preferred over submitting Trac tickets. Submitting a Pull Request will likely result in your contribution being merged into MacPorts much faster, as the workflow is much easier for the maintainers.
Extend 8. Glossary from the utter stub
Chapter 8. MacPorts Guide Glossary
Glossary
This section defines a number of words which may be new to the reader. These are all defined in the context of Macports instead of as general purpose definition.
However, does not meet the expectations of the reader who would welcome a true glossary and not a stub with a list of terms mostly if not all remaining rather unexplained.
TBD
TBC
Continuity
For the former Backlog and some of my notes on this documentary trials as of:
- 2023-01-08
- tbc
Ignorance is a bliss. Learning and improving is fun.
NOTE: Found nothing reasonable on how to wrap long texts and like my notes more located in my domain anyway.
Hope this helps.
🌻
THX - Apparently, it helped me to do my job as new maintainer of some little port called minetest.
If you like, have a look at my funny ideas of new subport definitions as Portfile amend in my first draft release at:
- WIP and moving target - stay tuned
Have fun.
Amend:
section 5.6. Tcl Extensions & Useful Tcl Commands
External program execution
Use only when ....
I am not quite sure I understand what this PR is about. But as I see you mentioned the adoc/ directory, please note that this was auto-generated from the DocBook XML at some point in the past (last time 2020). All changes to adoc/ will be lost when the conversion scripts runs again, so all updates for the guide should only be made to the DocBook XML.
I added the AsciiDoc conversion in the past to attract more interest and help for the conversion, but it did not gain more traction. I actually think it should be deleted from the repository at this point, because it is more confusing than it does help. I am sorry for this mess.
More information can be found in the corresponding ticket for the AsciiDoc conversion: https://trac.macports.org/ticket/56046#comment:3
I am not quite sure I understand what this PR is about. But as I see you mentioned the
adoc/directory, please note that this was auto-generated from the DocBook XML at some point in the past (last time 2020). All changes toadoc/will be lost when the conversion scripts runs again, so all updates for the guide should only be made to the DocBook XML.
Good to know and I will disband my misled work on adoc/ accordingly.
However, please consider my volunteering preliminary role at https://trac.macports.org/ticket/36957#comment:19
I added the AsciiDoc conversion in the past to attract more interest and help for the conversion, but it did not gain more traction. I actually think it should be deleted from the repository at this point, because it is more confusing than it does help. I am sorry for this mess.
Understood. Anyway a good learning experience and I am seeking to make myself more familiar with MacPorts and the MacPorts Guide anyway.
More information can be found in the corresponding ticket for the AsciiDoc conversion: https://trac.macports.org/ticket/56046#comment:3
I will consider in adding my a.m. Backlog content into your a.m. trac ticket or the b.m. trac ticket or another new trac ticket in due time.
- https://github.com/macports/macports-guide/pull/53#issuecomment-1374804353
- https://trac.macports.org/ticket/36957
Furthermore, IMO the Guide was somewhat unclear if MacPorts prefers GitHub (lacking Issue availability apparently) over Trac tickets or not.
THX - First things first and I will accomplish my work on subport amendments to 'minetest' before furthering this PR.