Support app descriptions

[lberrymage]

• [x] Add support for short descriptions
  • [x] Add support for submitting short description updates for existing apps
  • [x] Require short descriptions for new apps in console
  • [x] Add support for rendering short descriptions in client
• [ ] Add support for long descriptions
  • [ ] Add support for submitting long description updates for existing apps
  • [ ] Require long descriptions for new apps in console
  • [ ] Add support for rendering long descriptions in client

[lberrymage]

Developers should be able to submit descriptions along with their app. These descriptions should follow a (potentially versioned) well-defined format in the unsigned repository metadata; HTML formatting will not be supported. For the initial implementation, developers should be able to submit a description for one of their existing apps including a short (~80 char max) description along with a significantly longer long description which can be sectioned into paragraphs.

[PatrykMis]

If there will be website for listing/searching Accrescent apps too, the HTML format should be supported, so I think markdown format would be good as it supports paragraphs, lists, headings and eventually tables or images.

[lberrymage]

Something like markdown would be ideal. The reason I call out HTML is mostly for rendering purposes. I'd rather not render untrusted HTML via WebView just for the app description. Sanitizing that for script injection etc. is another opportunity for error that I don't think is necessary for a feature this simple.

The source format doesn't matter as much for the website since the pages will need to be generated from the metadata anyway, although markdown may make that easier.

Looking into it more, I think we could use commonmark-java to create an AST, and instead of rendering it to HTML, pass it to Compose to generate a composable tree as described in this article. I really like that idea initially.

[lberrymage]

Rendering from the AST ourselves also presents another advantage: we can explicitly choose what to support rendering. For example, if we don't want to support images in the description, we can choose not to render them, or if we only want to allow two levels of headings instead of six, we can do that.

Limiting the format in this way ensures a degree of consistency across the board which makes descriptions both more aesthetically pleasing and, in my opinion, more useful since users can hold consistent expectations for what an app description includes.

[keunes]

In terms of where to source the descriptions from, it would be great if existing structures/folder locations used already by Google Play and/or F-Droid could be re-used, as to limit the effort for existing apps.

[lberrymage]

What do you mean? Developers will upload/update descriptions through the developer console (or eventually its API), so I'm not sure what could be re-used per se.

[matchboxbananasynergy]

A few thoughts on this:

All apps should submit both a short and longer description.

Descriptions should not include:

• Images - Those should be their own section, either above or below the description.
• Links - There should be a dedicated links sections below the description. Developers should be able to choose from a dropdown of predefined link "types" (Website, Docs, Donate, Source Code etc.) and then put the link. Those sources should be automatically sorted by Accrescent regardless of the order that the developer submits them in to ensure consistency, and reviewers should check that there are no links in the description, and that the link labels actually make sense (i.e. the link for docs actually goes to docs)

We should have guidelines for how the descriptions should be structured to ensure that they are as uniform across different apps as possible. I wonder if Play Store has any guidelines for how developers should ideally write app descriptions? That'd be nice to see.

[keunes]

What do you mean? Developers will upload/update descriptions through the developer console (or eventually its API), so I'm not sure what could be re-used per se.

For AntennaPod, Triple-T is used to manage the metadata. F-Droid understands & respects the file structure: https://f-droid.org/en/docs/All_About_Descriptions_Graphics_and_Screenshots/#triple-t-structure

I guess what I had in mind is some uploader tool for Accrescent that leverages this file structure as well (or maybe even get support for release management in Fastlane for Accrescent).

wonder if Play Store has any guidelines for how developers should ideally write app descriptions? That'd be nice to see.

Here's what I could find:

• Google
  • Requirements and recommendations (covering short description & images): https://support.google.com/googleplay/android-developer/answer/9866151#zippy=%2Cshort-description
  • Developer Program Policies (all content): https://support.google.com/googleplay/android-developer/answer/9898842
• F-Droid
  • Short description: https://f-droid.org/en/docs/Build_Metadata_Reference/#Summary
  • Long description: https://f-droid.org/en/docs/Build_Metadata_Reference/#Description

[salim-b]

Just a hint: You might wanna take inspiration from the AppStream standard from the Linux Desktop world. Docs are here.

I'm no Android developer, but I guess it could be beneficial in the long term to at least come up with something easily convertible to/from AppStream metadata (and not reinvent the wheel, as the saying goes ☺️).

[lberrymage]

Implementation has begun at https://github.com/accrescent/parcelo/tree/descriptions.

[lberrymage]

Short descriptions are now merged into main and slated for next week's release.

[lberrymage]

I'm deprioritizing long descriptions for a little while to prioritize infrastructure and scaling improvements, while are now reflected in the roadmap.