docs: modernize to Markdown + audit staleness + fix broken README icon URL - #514
Merged
Merged
Conversation
The README's icon image referenced amule.png at the repo root, but PR amule-project#508 (icons modernize) renamed every icon to follow the AppStream component-id convention org.amule.aMule.<ext>. amule.png no longer exists at the GitHub raw URL, so the README rendered with a broken image since amule-project#508 merged. Update the URL to the new filename. While in the file: * Switch from underline-style headings to ATX (#) headings — more common in Markdown ecosystems and renders identically. * Replace the autotools-era 'configure && make' compile snippet with the actual cmake invocation, and link to docs/INSTALL.md for the full dep list. The wiki's compile pages are flagged 'may be outdated' upstream; pointing at the in-tree INSTALL keeps this reference always-current. * Drop the X-Box claim from the supported-platforms list — that's pre-2010 historical and isn't tested today. * Update the supported-platforms list to current reality (Linux, FreeBSD, OpenBSD, macOS, Windows MSYS2 / mingw-w64, x86_64 + ARM64). * Drop the dead bugs.amule.org link; GitHub Issues is the canonical bug tracker. * Tighten the prose throughout — same content, fewer filler words.
* docs/TODO is 29 bytes of 'Lots of stuff. Ask a dev.' Useless. * docs/ABOUT-NLS is 24KB of generic FSF gettext boilerplate from the autotools era — installed by gettextize into every gettext-using package. aMule moved to CMake and uses gettext only at build time to compile .po → .mo; the upstream 'how to use gettext' tour doesn't apply. Anyone wanting it can read it at the gettext upstream. Distros that still ship aMule with this file are duplicating their gettext package's copy. * docs/README duplicates content already in the root README.md (which was also touched in this PR to fix a broken icon URL), with stale extras: 56k modem references, dead 'Update server.met from URL' addresses pointing at ocbmaurice.dyndns.org, file-type list missing modern formats, and a closing 'Last modified Thu Apr 7 18:06:32 CEST 2016' timestamp. The user-guide content here belongs on the wiki, which the README already links at. Also wire docs/IP2Country.md into the install list — it was added by PR amule-project#502 (libgeoip → libmaxminddb migration) but never reached docs/CMakeLists.txt's FILES list, so distro packages have been shipping without it. The list stays alphabetised.
Renames:
docs/AUTHORS -> docs/AUTHORS.md
docs/EC_Protocol.txt -> docs/EC_Protocol.md
docs/INSTALL -> docs/INSTALL.md
docs/amulesig.txt -> docs/amulesig.md
Modernization per file:
* INSTALL.md — light MD pass: requirements + optional deps as
tables, headings as ATX (# / ## / ###), file-system links
rewritten as proper relative MD links to IP2Country.md and the CI
workflow file. Build-options section gains a 'Default' column so
readers don't have to grep cmake/options.cmake to know what's on
by default. Content unchanged.
* EC_Protocol.md — full Markdown conversion. ASCII-art title block
collapsed into a single H1 + tagline blockquote. Section headings
become ATX. The bit-description table in Section 1.1 is now a
proper Markdown table. Packet structures (`OPCODE`, `TAGNAME`,
…) are wrapped in C-fenced code blocks. The transcripted
authentication and stats-request example packets are wrapped in
fenced code blocks so monospace alignment survives every
Markdown renderer. The Section 4 Notable Tag Types table is now
a proper MD table with Code/Type/Description columns. Every
normative byte / value / type / opcode is preserved verbatim;
only formatting changes.
* AUTHORS.md — drop the ASCII-art double-pipe borders, convert
group labels to H3, names to bulleted lists. Email angles
rewritten as <…> HTML entities so MD doesn't try to interpret
them as auto-link tags (which would expose the addresses to
scrapers via mailto: rendering anyway). Roster unchanged. Not
added to the install list — matches upstream behaviour.
* amulesig.md — convert the field-table to a real Markdown table
with proper column headers per session-state. The four columns
('Not running', 'Offline', 'Online', 'Connecting') were aligned
with tabs in the plain-text version and broke at almost every
monospace renderer. Content unchanged.
docs/CMakeLists.txt updated for the .md filenames + alphabetised.
Behavioural diff: every reference doc (sans Changelog and the
license) now renders nicely on GitHub and gets installed under
${CMAKE_INSTALL_DOCDIR}.
The previous docs/README (deleted in the prior commit) was a 9-year-old
copy of the root README with extra stale user-config trivia. Rather
than resurrect it, ship a different document at docs/README.md scoped
specifically to *end-user* concerns:
* What each binary is and when to use it (amule / amuled / amulegui /
amuleweb / amulecmd / ed2k).
* First-run checklist: ports for HighID, realistic up/down limits
with a concrete example using Mbps→kB/s arithmetic, and the
'don't share blanket /home or system trees' safety rule.
* Headless amuled setup walkthrough.
* Reading the per-file and per-source progress-bar colours.
* A modern file-types table (replaces the original which had .ace
and .vivo but missed mkv / opus / AppImage).
* Troubleshooting pointers for LowID, generic launcher icons,
AppImage menu integration, and missing GNOME tray icon.
* A short safety / legal note.
Scope is deliberately complementary to the top-level README:
* root README.md = project overview, build pointer, contributing,
upstream / downstream links
* docs/README.md = user guide, day-to-day operation, troubleshooting
Wired into docs/CMakeLists.txt's install list so distro packages
ship it alongside the other reference docs.
Light-touch conversion to make the existing Changelog render properly on GitHub: * Add a top-of-file H1 + one-line lead so the rendered page has a proper title and isn't just a wall of text. * Convert the per-version 'Version X.Y.Z - The "..." version.' + underline into '## Version X.Y.Z — "..."' ATX heading. Side benefit: GitHub now generates table-of-contents anchors for every release that other docs / commit messages can link to (e.g. https://.../docs/CHANGELOG.md#version-233-). * Convert the inter-version 80-dash separator lines into Markdown horizontal rules (---). Body content is preserved verbatim — contributor names, bullet lists, and all 7000+ lines of release history are unchanged. The dash-form version subtitles get an em-dash for typographic polish (no semantic change). docs/CMakeLists.txt updated for the rename. The CHANGELOG.md filename matches the convention every modern open-source project uses; older GitHub conventions auto-render either Changelog or CHANGELOG.md as the release notes, but only the .md form gets proper anchors and styled headings.
Contributor
|
There are some missing names in the AUTHORS file. In a quick view,
Maybe other more rencent folks, we can add them later, but sure those must go in. |
…3nks mrjimenez flagged on PR amule-project#514 review that these three contributors were missing from the roster: * Werner Mahr / Vollstrecker — has merge access on amule-project/amule and merges incoming PRs (e.g. amule-project#430, amule-project#385, amule-project#319, amule-project#330, amule-project#286). Goes under Maintainers based on that role. * Pablo Barciela / Sc0w — recent contributor, e.g. wxWidgets 3.2.6 build fixes, GTK version-check cleanup, dropping gtk1/gtk2 support, Chinese translation work. Goes under Developers. * got3nks — Wayland app_id binding + SNI tray (amule-project#508), macOS UX (amule-project#508), libmaxminddb CI fix (amule-project#507), ip2country/upnp/nls/boost hard-fail series (amule-project#509/amule-project#511/amule-project#512/amule-project#513), packaging (amule-project#510), docs modernize (this PR). Goes under Developers. Other recent folks may be missing too — those can be added in follow-up commits as they're identified. mrjimenez explicitly noted this is the priority subset to not block the rename PR.
Contributor
Author
|
Submitted a new commit. |
2 tasks
mrjimenez
pushed a commit
that referenced
this pull request
May 2, 2026
…lity The libupnp 1.18.4 cmake build hard-codes lib64 as the install directory on both x86_64 and aarch64 — its CMakeLists doesn't go through GNUInstallDirs the usual biarch-aware way. As a result libupnp.pc + libupnp.so end up at /app/lib64/, but Flatpak's downstream PKG_CONFIG_PATH only searches /app/lib/pkgconfig/. aMule's cmake/upnp.cmake then can't find libupnp via pkg_check_modules and (since #511 made ENABLE_UPNP=YES a hard requirement) errors out. Before #511 this silently produced a Flatpak with no UPnP support — symptom went unnoticed because the existing test plan didn't cover UPnP port forwarding from inside the sandbox. Fix: pass -DCMAKE_INSTALL_LIBDIR=lib to libupnp's config-opts. Same pattern already applied to the ayatana-* libs further down in the manifest for the identical reason. libupnp.pc now lands at /app/lib/pkgconfig/libupnp.pc, pkg-config finds it, ENABLE_UPNP resolves true, the build completes. Affected runs: the first amule-project/amule:master Packaging run after #510-#514 merged (https://github.com/amule-project/amule/actions/runs/25253858400) where Flatpak (aarch64) failed at the amule cmake step with the new #511 FATAL_ERROR. Verified locally that the same regression existed on x86_64 too.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Five-commit PR that modernises the in-tree docs:
README.md— fixes the broken icon URL (amule.pngwas renamed toorg.amule.aMule.pngin desktop integration: Wayland app_id, SNI tray, macOS dock-restore + tray opt-in (closes #410) #508 — the README's image link has been 404 since that merged), plus light modernization (cmake snippet instead ofconfigure && make, drop X-Box from supported-platforms, link todocs/INSTALL.md).docs/TODO(29 bytes of "Ask a dev"),docs/ABOUT-NLS(autotools/gettext FSF boilerplate, doesn't apply post-CMake), and the olddocs/README(9-year-old, redundant with the root README — commit 4 adds a newdocs/README.mdwith a distinct user-guide scope). Also wiresdocs/IP2Country.mdinto the install list (was added by IP2Country: swap libGeoIP for libmaxminddb (.dat → .mmdb) #502 but never reacheddocs/CMakeLists.txt).INSTALL.md,EC_Protocol.md,AUTHORS.md,amulesig.md. Real MD tables for dep lists / build options / EC bit fields / online-signature columns. Code fences for the packet-structure transcripts. All normative content preserved verbatim.docs/README.md— user-facing guide (different scope from the root README): per-binary "what / when to use it" table, first-run checklist (HighID ports, realistic up/down limits, share-folder safety), headlessamuledsetup, progress-bar colour reference, modern file-types table, troubleshooting pointers.Changelog→CHANGELOG.md— light-touch MD pass: top H1, per-version ATX heading (so GitHub generates anchors), horizontal-rule separators between versions. 97% byte-identical (git detects rename).Net effect: every reference doc now renders properly on GitHub and gets installed under
${CMAKE_INSTALL_DOCDIR}. The amule-project main repo page stops showing a broken icon. Reviewers / packagers / new users land on documents that match the project's current build system and platform support.Per-file rationale
README.md(root)Was last touched in 2014. Issues fixed:
amule.pngat the repo root; PR desktop integration: Wayland app_id, SNI tray, macOS dock-restore + tray opt-in (closes #410) #508 renamed every icon to follow the AppStream component-id conventionorg.amule.aMule.<ext>. The image has rendered as a 404 placeholder ever since desktop integration: Wayland app_id, SNI tray, macOS dock-restore + tray opt-in (closes #410) #508 merged.configure && makecompile snippet — that's autotools-era; aMule moved to CMake well before this. Replaced with the actualcmake -B build … && cmake --build build && sudo cmake --install buildinvocation.bugs.amule.orglink — GitHub Issues is the canonical bug tracker.ATX (
#) headings throughout instead of underline-style — same render, more common Markdown convention.Removed and replaced
docs/TODO— 29 bytes total:Lots of stuff. Ask a dev.Useless.docs/ABOUT-NLS— 24KB of FSF gettext boilerplate dropped in bygettextizefrom the autotools era. Documents./configure --enable-nls, theintl/directory layout, and other autotools-specific machinery aMule no longer uses. Anyone wanting the general "what is the GNU Translation Project" tour can read the upstream gettext manual at https://www.gnu.org/software/gettext/manual/.docs/README— duplicates content already in the rootREADME.mdwith stale extras: 56k modem references, deadUpdate server.met from URLaddresses pointing atocbmaurice.dyndns.org, file-type list missing modern formats, closingLast modified Thu Apr 7 18:06:32 CEST 2016timestamp. Replaced by a freshdocs/README.md(commit 4) with distinct scope.docs/IP2Country.md(added in #502) is now in the install list — that file currently isn't shipped bycmake --install.Reference-doc conversions
INSTALL.md— light MD pass. Requirements + optional deps as tables. Build-options gains a Default column so readers don't have to grepcmake/options.cmake. Cross-doc links use proper relative MD links toIP2Country.mdand the CI workflow file.EC_Protocol.md— full Markdown conversion. ASCII-art title block collapsed into a single H1 + tagline blockquote. Section headings as ATX. The bit-field description in Section 1.1 is now a proper MD table. Packet structures (OPCODE,TAGNAME, etc.) wrapped in C-fenced code blocks. The transcripted authentication and stats-request example packets wrapped in fenced code blocks so monospace alignment survives every renderer. Section 4 Notable Tag Types is a real MD table with Code/Type/Description columns. Every normative byte / value / type / opcode is preserved verbatim; only formatting changes.AUTHORS.md— drop the ASCII-art double-pipe borders, convert group labels to H3, names to bulleted lists. Email addresses HTML-encoded so MD doesn't auto-link them. Roster unchanged. Not added to the install list — matches upstream behaviour where AUTHORS isn't shipped.amulesig.md— convert the field-table to a real Markdown table with proper column headers per session-state. The four columns (Not running,Offline,Online,Connecting) were tab-aligned in the plain-text version and broke at almost every monospace renderer. Content unchanged.docs/README.md(new)Separate scope from the root README: a true user guide rather than a project overview. Sections:
amule/amuled/amulegui/amuleweb/amulecmd/ed2k) with "what it is" and "when to use it" columns./etc,/var,/home-blanket" warnings.amuledfirst-time setup walkthrough with the EC password configuration step.opus, video getsmkv/webm/mp4, archives get7z/zst/xz, etc. The original list had.ace,.vivo, and.rambut missed everything from the last decade.Cross-links the root README, INSTALL.md, EC_Protocol.md, and the wiki / forum / GitHub Issues. Wired into
docs/CMakeLists.txtso distro packages ship it.CHANGELOG.mdRenamed from
Changelog(git detects rename — 97% similar). Light-touch additions:# aMule ChangelogH1 + one-line lead, so the rendered page has a proper title.## Version X.Y.Z — "subtitle"ATX heading instead ofVersion X+ dash-underline. GitHub now generates table-of-contents anchors that other docs / PR descriptions / commit messages can link to.---horizontal rule.The 7000+ lines of release history themselves — contributor names, bullet lists, dates — are byte-identical to the previous version.
Test plan
cmake --install buildships the renamed.mdfiles to${CMAKE_INSTALL_DOCDIR}(verified locally on macOS).README.mdicon URL is reachable:curl -sI https://raw.githubusercontent.com/amule-project/amule/master/org.amule.aMule.png→ 200 OK; the previousamule.pngreturned 404.git log --followworks correctly across the renames (Changelog→CHANGELOG.mdrename detection preserves history; AUTHORS / EC_Protocol / INSTALL / amulesig were rewritten enough that git treats them as add+delete, butgit log --followtraces them via the path-similarity heuristic).No breakage from renames / deletions
Grepped the entire repo for stale references to the deleted / renamed files; full results below.
docs/TODO,docs/ABOUT-NLSbuild-*/cmake_install.cmakeartifactsdocs/Changelogbuild-*/cmake_install.cmake, plusemule-src/miniupnpc/Changelog.txt(different file — vendored upstream miniupnpc, unrelated)AUTHORS,amulesig.txt,EC_Protocol.txtdocs/CHANGELOG.mditself — historical changelog entries (Fixed AUTHORS file,Updated AUTHORS file,Fixed README, amulesig.txt) describing past commits when the files had those names. Rewriting them would be revisionist; left verbatim.docs/INSTALLREADME.md, already updated todocs/INSTALL.mdin commit 1The local
build-*/cmake_install.cmakeentries don't matter — they regenerate on the nextcmake -B buildinvocation. The repo doesn't ship.spec/debian/files; distro packagers maintain those externally and will catch any rename when building the next release. PR #510 (currently in flight, same fork) does add apackaging/tree, but it's recipe-only and references zerodocs/files — grep verified clean.