In case you haven’t seen this yet, apps.gnome.org is a thing now and it is awesome!
Sophie Herold and others have done a great job at creating visually appealing pages to browse our app catalog that require very little maintenance.
If you’ve been around for a while, you probably know how cumbersome it has become to main pages in wiki.gnome.org. After some attacks, the wiki is now protected and only “TrustedEditors” get to make changes in it.
The wiki has a rich (but complex) markup syntax that can be quite helpful for structured content that requires constant update with multiple contributors. But when it comes to app landing pages, it fails to provide a consistent and appealing page for app users to get to know more about our apps. We are currently updating the app pages manually. Lots of them are outdated.
I think ditching wiki.gnome.org/Apps in favor of apps.gnome.org can make us provide consistency with the info presented in GNOME Software, KDE Discover, Flathub, etc… and estimulate the community to provide better appdata content (descriptions, translations, screenshots), etc… all while saving us from manually updating wiki pages.
While I wholeheartedly agree that we should move a lot of static content from the black pit of despair that is wiki.gnome.org, I also think that apps.gnome.org isn’t going to be useful for everything an app page would normally contain—especially because the appdata spec is very lightweight on the content, and maintainers are also stuck between the two different (but equally undocumented) appdata validating rules of appstream and Flathub.
the apps.gnome.org page is definitely more useful for a user, with links to the issue tracker, but it’s missing all the information about licensing and development
the wiki page is kind of terrible, and out of date like a lot of the wiki, but it provides links to additional documentation, projects, and resources, including where to find the code
The apps.gnome.org page should probably include more information:
the licensing terms of the project
the latest release notes, not just the release version and the date
a link to the source code repository
But, in any case, we still need some sort of “website” for the application—which could be a page on the wiki, or the GitLab project wiki space, or some sort of GitLab pages website. For those, we should still have some sort of consistent appearance or style.
That’s certainly something that should be addressed. It’s not only validating. Currently, Flathub also removes information like figure captions or supported screen dimensions. Not sure how soon the move away from appstream-glib will be completed for Flathub. But it looks like something is happening.
We would need to parse the format to display them properly (i18n). Haven’t checked if there is a parser for the format. Currently, they appear only at the bottom of the page because the page content is somewhat under this license as well.
Release notes are a tough one. I would love to add them, also for SEO reasons (google likes changing content afaik.) But release notes are in a very inconsistent, often bad, state. For Core apps, they often don’t exist at all. And finally, they are not translated. We would have to fix all those parts before they could be added to a.g.o. They are actually integrated in a hidden way. Just add /releases.html to the end of an app page URL.
We could do this. It’s kind of covered by the issues link. I’m currently guessing the repository URL from the issues URL. Was thinking about prosing adding a source code URL to the AppStream standard.
To be honest, I don’t think that every app will maintain an additional page and most projects shouldn’t. I think that a lot of Circle apps for example can cover their needs with a README.md and CONTRIBUTING.md.
My main problem with the GitLab Wiki is, that only people with committer rights can contribute. And even then, maintainers probably want to review changes, which gets complicated without merge requests. I would probably prefer solutions that work via the git repository because things will be more in people’s sight, can be changed via merge requests, and one might even grep things when doing mass changes.
Do you (or others) have any examples for wiki pages that have information that neither fit into a.g.o. nor GitLab issues/README.md/CONTRIBUTING.md? That would be helpful for figuring out what’s actually needed.
Related topic: I think that we should generate “how to contribute” pages out of the a.g.o. data for every app.
Indeed, this would be a good incentive to get people to actually write release notes (and then generate the NEWS file from them). Sadly, this is another case of broken appstream/flathub validation, as the version sorting in the appdata does not deal well with GNOME’s versioning scheme; and flathub has its own validation rules as well.
Doesn’t a.g.o also consume the DOAP file data? Because there’s a good source of ancillary information in there.
I’m not very worried about third party contributions to an app’s wiki/home page. We’ve had them for a decade, and that hasn’t pushed anybody to contribute to them anyway.
The way maintainers use the Apps/ (and Projects/ for libraries) space in the wiki is to add planning pages; or additional developer documentation for new contributors; or any other ancillary documentation that does not have a place inside the application help.
We really should; it’s a classic question for newcomers. I’ve had moderate success in “standardising” the projects I maintain, or contribute to, by using Nadia Eghbal’s excellent contribution template. We could literally generate a stock contribution document by using the template and filling out some of the details from the project metadata, if we can’t find a CONTRIBUTING.md file in the source repository.
Would you make them translatable in this case? That would probably imply removing the “new/updated translation” parts from release notes because otherwise there would be an infinite cycle for translating release notes.
Heh. Yes. But I’m getting the DOAP file from the repository
I think apps can package it but most apps don’t do it? Not sure.
It’s a hard question. I haven’t checked if release notes for applications are actually translated on my phone, to be fair. As for “translation updates” lines: some maintainers do go the extra mile to say which translations were updated; I guess if the release notes for an app were to be translated, then the translation for language X would probably mention that the translation has been added/updated. Otherwise, to be quite honest, I see not much value in noting that a translation has been updated at all: we do it for inertia, and because it’s nice to acknowledge the work on localisation teams, of course; but “updating a translation” is kind of obvious, because if it weren’t updated, you’d see half the UI in English.
Regarding translation of release notes, for Metadata Cleaner (a Circle app), they are translated. However, when someone adds a new language, they have two choices:
Translate all the past release notes, but that could be a lot of work if the software is old and has a lot of release notes
Only translate release notes from the point they started the translation, but old release notes are still displayed in the original language in the software center
For these reasons, I try to keep my release notes as succinct as possible, only outlining new features and using generic notes for translation updates and bug fixes, so that the burden on translators is minimal. The detailed changes are in the CHANGELOG.md file and the release attached to the tag on the repository, giving proper credit to the contributors.
For example Apps/Evolution - GNOME Wiki! contains a lot of subpages. Even they can be mostly seen as a developer/contributor content, there can be saved also things referenced from the code. The Evolution has one (Apps/Evolution/EWS/OAuth2 - GNOME Wiki!). I do not like to have tons of .md files in the git repo, also because the repo is used to create the release tarball (using git archive command).
Hi,
aha, I see. The evolution-data-server is “official”, and it is part of
the wiki under /Apps/Evolution. Basically those to coexist together.
My point is that it would be quite unfortunate if you just close the
Apps/ wiki in favor of the apps.gnome.org for everyone, without a
replacement/migration, even of the outdated content (I agree, the
content on Apps/ wiki gets outdated very soon).
Bye,
Milan
I don’t think the wiki.g.o/Apps/ section should be closed entirely. I just think it isn’t quite fit as the landing page for most apps. It should be OK to continue linking to wiki pages for additional information, such as these Evolution setup instructions.
I also never had any intentions of “closing” the /Apps/ section.
We should probably still maintain the /Apps overview, at least for a while? And it would be interesting if wiki pages could redirect to other pages. Personally, I would prefer a redirect for my old Pika Backup page.
