AntennaPod
Contributor documentation
Short description: Add contributor documentation.
Location:
Why have this:
From https://github.com/AntennaPod/AntennaPod/pull/6834#discussion_r1439050615:
It would be nice if there was an easy way to auto-format it according to the requirements but I didn't see anything in the contributor guide
The contributor's page for 'Develop' links to this wiki page: https://github.com/AntennaPod/AntennaPod/wiki/Code-style. Apparently it's not visible enough.
Also, the Contribute > Translations page is rather long and complicated.
More info:
Pages to include:
- Requesting new languages
- Using Weblate
- Code style
- Building AntennaPod
- About debug versions
Also to mention somewhere:
- Discussions on functionality in the Forum
- Concrete/boiled down solution descriptions in Issues
- Technical/Implementation discussions in PRs
I'm still not really convinced that the public website should hold very technical stuff like the developer documentation. The comment linked above doesn't imply that they did not find the developer documentation. It just says that the developer documentation does not contain what they were looking for (now it does).
The comment linked above doesn't imply that they did not find the developer documentation. It just says that the developer documentation does not contain what they were looking for (now it does).
I didn't realise you edited the wiki page to add the info :-)
I'm still not really convinced that the public website should hold very technical stuff like the developer documentation
It doesn't have to be in the menu, confusing 'regular' users. But as a) important information for contributors is currently spread over different places and b) hard to process (at least the translations), we need to do something to address both issues.
And as our main website goal is to attract contributors and ensures a good mix of controllability and openness (using PRs, impossible combination on the wiki), I find it the most appropriate place. (But if you have another proposal that addresses identified issues, I'm all ears.)
This issue has been mentioned on AntennaPod Forum. There might be relevant details there:
https://forum.antennapod.org/t/project-management/3879/3
Was your idea to completely remove the wiki and the CONTRIBUTING.md file from the main app repo to have everything in one place?
My idea was indeed to drop the wiki entirely. CONTRIBUTE.md probably not, as it's a recognised standard. However, if we have a contributor's section, we should limit it to key information & pointers.
If we do this, I would limit the CONTRIBUTING.md file to just contain a link to the website. Then we really have everything in one place. Otherwise we move from wiki+repo to website+repo, so the information would still be spread over different places.
I assume the contributor documentation won't get translated, right? Translating variable naming guidelines and stuff doesn't make a lot of sense because the variables themselves should be in English anyway. Also, contributions are discussed in English as well.
I assume the contributor documentation won't get translated, right?
Yeap, agree.
I could help with (at least parts of) these documentation pages next, starting with the translation bits.
However, I have a few questions before I set myself to the task:
- Is the migration away from Transifex going to be completed soon? That would help streamline the current documentation.
- Do you have a preference between keeping all translation-related guidance on one page vs. splitting it in multiple pages (e.g. (1) app, (2) website + other materials)?
- Why do we need to have our own documentation on using Weblate? Isn't it sufficient to point to the Weblate documentation as we currently do?
- How about the maintainer documentation on updating translations? Do you see any value in it? I would assume not.
Why do we need to have our own documentation on using Weblate? Isn't it sufficient to point to the Weblate documentation as we currently do?
I agree. This would just mean we would have to keep it up to date.
How about the maintainer documentation on updating translations? Do you see any value in it? I would assume not.
I never used it. It's probably outdated anyway since Transifex changed their client some years ago
This issue has been mentioned on AntennaPod Forum. There might be relevant details there:
https://forum.antennapod.org/t/monthly-community-call/1869/71
I'm looking into migrating more content.
Can you confirm if these pages can be safely deleted (perhaps after making a local backup in case needed)?
- https://github.com/AntennaPod/AntennaPod/wiki/Issue-label-categories
- https://github.com/AntennaPod/AntennaPod/wiki/Sorting-criteria
- https://github.com/AntennaPod/AntennaPod/wiki/Infrastructure-documentation
- https://github.com/AntennaPod/AntennaPod/wiki/Releasing-a-New-Version
- https://github.com/AntennaPod/AntennaPod/wiki/Latest-version-on-F-Droid-(not-up-to-date) (already covered in https://antennapod.org/documentation/general/f-droid)
For the remaining pages, can we try to make all content fit as sections of the Develop > App page? This structure could make sense:
- Where we need help
- Getting started - to be reworked and to include Discussions on functionality in the forum / Concrete/boiled down solution descriptions in issues / Technical/Implementation discussions in PRs
- Code structure
- Code style
- Getting test builds
- Obtain logs for debug
- Getting credited on the Contributors page
Great, thanks @loucasal!
- https://github.com/AntennaPod/AntennaPod/wiki/Latest-version-on-F-Droid-(not-up-to-date) --> We already have a page on the website
- https://github.com/AntennaPod/AntennaPod/wiki/Releasing-a-New-Version --> This process is not currently followed; can be deleted. Maybe @ByteHamster will write a new, updated version in future.
- https://github.com/AntennaPod/AntennaPod/wiki/Infrastructure-documentation --> Can be moved over (was just updated)
- Could be moved under a single Infrastructure page, under
/contribute/infrastructure. But we don't really know how to distribute then. - We think it's better to have these details (maybe on a dedicated page) per contribute category:
- App distribution + Development --> Develop > App
- Web + Email --> We're thinking of a new 'Sysadmin' group/task. To think about this further.
- Social media --> Promote
- Could be moved under a single Infrastructure page, under
- https://github.com/AntennaPod/AntennaPod/wiki/Sorting-criteria --> We already have a page on the website that explains smart shuffle. The only thing that's not really clear is 'Podcast title' because it keeps the
- https://github.com/AntennaPod/AntennaPod/wiki/Issue-label-categories --> Can be dropped; is essentially already documented in the labels itself.
For the remaining pages, can we try to make all content fit as sections of the Develop > App page?
Yes. Maybe Code structure & style can also be combined?
This issue has been mentioned on AntennaPod Forum. There might be relevant details there:
https://forum.antennapod.org/t/needs-decision-meeting-updates/4169/21
Alright, only two pages left.
- https://github.com/AntennaPod/AntennaPod/wiki/Infrastructure-documentation -> Even after re-reading the outcome of your discussion, I admit I can't imagine this as website content, and even less so if we split it across multiple pages. As I assume that you intend to keep this public, how about a forum post under the "Project management" category?
https://github.com/AntennaPod/AntennaPod/wiki/Sorting-criteria --> We already have a page on the website that explains smart shuffle. The only thing that's not really clear is 'Podcast title' because it keeps the
@keunes I think part of your sentence got lost, do you remember more details?
If the disclaimer on the wiki page is still applicable (i.e. it is only a proposal), then the relevant content should be moved to an issue rather than to the website.