Libretime: Problem: The documentation is out of date

[Robbt]

This is an attempt to create a list of all assets and info on the LibreTime manual at libretime.org that need to be updated as they refer to an old version of 2.5.1 or we have changed the features etc.

Pages in need of update

• [x] [Features](http://libretime.org/features/) - is all TBD
• [x] [On The Air in 60 seconds](http://libretime.org/manual/on-air-in-60-seconds/) - needs instructions refined for LibreTime
• [x] [GettingStarted](http://libretime.org/manual/getting-started/) - remove info about Registering since we don't do that - and need to update Image assets w/ new screenshots thanks @nikmartin
• [x] [Systems-General](http://libretime.org/manual/preferences/) - refers to settings that don't exist like Soundcloud and e-mail settings - how do we handle e-mail w/ LibreTime ?
• [x] [Users](http://libretime.org/manual/users/) - needs updated screenshots
• [x] [Media Folders](http://libretime.org/manual/media-folders/) - this functionality doesn't exist in LibreTime should be at least updated w/ a notice and link to PR
• [x] [Stream Settings](http://libretime.org/manual/stream-settings/) - at least need to update and remove Scheduled Play as we don't have that feature
• [x] [Support/Feedback](http://libretime.org/manual/support-feedback/) - put info about Fork and links to Github and discourse forum vs. referring to SourceFabric
• [ ] [Listen](http://libretime.org/manual/listen/) - needs new screenshots
• [x] [Upload](http://libretime.org/manual/upload/) - needs new screenshots for new UI
• [x] [Tracks](http://libretime.org/manual/tracks/) - needs updated screenshots
• [x] [Playlists](http://libretime.org/manual/playlists/) - needs updated screenshots and maybe updating how to create and manage playlists. Needs to talk about Autoloading playlsts
• [x] [SmartBlocks](http://libretime.org/manual/smartblocks/) - updated screenshots
• [x] [WebStreams](http://libretime.org/manual/webstreams/) - updated screenshots
• [x] [Podcasts](http://libretime.org/manual/podcasts/) - Replace the TBD stuff with content
• [x] [Calendar](http://libretime.org/manual/calendar/) - UPDATED - could use a little bit more info on automatic playlists
• [x] [Help](http://libretime.org/manual/help/) - needs links to LibreTime
• [x] [Recording](http://libretime.org/manual/recording-shows/) - currently not supported by LibreTime - needs info regarding this
• [x] [Install](http://libretime.org/install/) - should refer to ./install -fiap for most purposes
• [x] [Preparing Server](http://libretime.org/manual/preparing-the-server/) - need to remove reference to system / and debian squeeze as we don't support that. Possibly add info regarding distro etc.
• [x] [Automated Installation](http://libretime.org/manual/automated-installation/) - we haven't done this - so should remove it from the page or link to issues regarding it
• [x] [Manual Install](http://libretime.org/manual/manual-installation/) - no different than Install but has outdated info regarding 2.5.1
• [x] [Airtime Log](http://libretime.org/manual/the-airtime-log-command/) - this command was removed in 2.5.2 maybe we should bring it back along with the status CLI for troubleshooting but at the moment this page needs updated.
• [x] [Airtime Backup](http://libretime.org/manual/backing-up-the-server/) - mostly OK
• [x] [Upgrading](http://libretime.org/manual/upgrading/) - this needs updated w/ LibreTime specific information
• [x] [TroubleShooting](http://libretime.org/manual/troubleshooting/) - needs info regarding systemd and upstart specific restart commands and how to access the logs
• [x] [Monit](http://libretime.org/manual/using-monit/) - test or remove for now as we haven't supported it
• [x] [Automated File Import](http://libretime.org/manual/automated-file-import/) - needs updating because it isn't supported at the moment
• [ ] [Player on Website](http://libretime.org/manual/stream-player-for-your-website/) - should update w/ widget
• [ ] [Export schedule](http://libretime.org/manual/exporting-the-schedule/) - test API info and also add widget instructions
• [x] [Interface Customization](http://libretime.org/manual/interface-customization/) - probably good info regarding CSS but maybe we want to make it so that it can be done w/o overwriting upon an upgrade and remove Airtime vocab
• [x] [Localization](http://libretime.org/manual/interface-localization/) - refer to the Zanata translation webpage not SourceFabric
• [x] [SSL stuff](http://libretime.org/manual/secure-login-with-ssl/) - maybe add info on Let's Encrypt etc
• [x] [Expert install](http://libretime.org/manual/expert-install/) - all outdated info here
• [x] [Autoloading Playlists](http://libretime.org/manual/calendar/#autoloading-playlist) needs new screenshot, explanation with a video

Stuff missing from Manual

• [x] * Podcasts
• [ ] * Changing Icecast passwords
• [ ] * Embedding Widgets

[matias-tecnosoul]

I volunteer to give a hand with this...

[frecuencialibre]

expert install, automated installation, manual install, and preparing the server should be checked off. would it be complicated for you give me the ability to do this myself?

[hairmare]

@frecuencialibre I checked the things you mentioned off.

To be able to do such tasks yourself you need write access to the repo. Currently our process for this is adding you to the @LibreTime/maintainers group. If you are willing to take on the position of being a Maintainer I would be glad to do so as you have clearly demonstrated the following:

A new Contributor who makes correct patches, who clearly understands the project goals, and the process SHOULD be invited to become a Maintainer.

Please take a look at the C4 contract to decide if you can see yourself becoming a Maintainer.

If you're ok with this and @Robbt chimes in and gives his ok I'll escalate your rights.

[frecuencialibre]

Thanks Lucas, yes, I would like to chip in as a maintainer. My availability may be inconsistent, as I sometimes have to deep dive into paid gigs and community commitments, but I am planning to stick with this project in order to provide a long-term solution for my local community radio.

I'd probably focus on

1. updating incorrect airtime documentation
2. potentially adding new documentation, such as use with docker, and content in spanish (some of which we already have).
3. issue queue cleanup, labeling, etc..
4. down the line perhaps some js stuff eg. with the web player https://github.com/LibreTime/libretime/issues/249 https://github.com/LibreTime/libretime/issues/461

I'd almost certainly not touch any php or python code for a _long time_. As I've mentioned to you Robb, my php learning stopped several years ago when i moved from building/theming websites with drupal and wordpress over to the world of javascript apps (react and angular so far, but interested in vue). My python knowledge is non-existent -- took me a million hours just to set an environment variable.

In general I can tell you've put a lot of work into setting this up well as a collective effort, and i like what i'm reading 1 2 3. I personally try to balance my obsessive-compulsive tendencies, which are often helpful in programming, with speed and real human interaction ;).

Regarding c4:

1. nitpick: i couldn't find any guidelines for code style as c4 mentions.
2. "If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue." this dos NOT happen, right? ie. let's create both issues and also separate PRs?
3. "Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days)." seems like this waiting period shouldn't be set in stone.
4. "Maintainers MAY merge incorrect patches from other Contributors with the goals of (a) ending fruitless discussions, (b) capturing toxic patches in the historical record, (c) engaging with the Contributor on improving their patch quality." this seems damaging to the project. perhaps merging them in newly created intentionally broken branch?
5. "The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches." so when somebody makes a PR to libretime master, i'd somehow apply that PR to a personal fork in order to test it?

thanks!
-r

[hairmare]

1. nitpick: i couldn't find any guidelines for code style as c4 mentions.

Yupp, we didn't get around to implementing those yet.

1. "If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue." this dos NOT happen, right? ie. let's create both issues and also separate PRs?

I don't understand this as an issue being mandatory for a later PR. The MAY part says it's perfectly ok do directly do a PR.

1. "Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days)." seems like this waiting period shouldn't be set in stone.

AFAIKT this isn't set in stone, in fact noone has merged their own PR after waiting only 2 days. It's more like we wait for 2 months before we merge as described in C4.

1. "Maintainers MAY merge incorrect patches from other Contributors with the goals of (a) ending fruitless discussions, (b) capturing toxic patches in the historical record, (c) engaging with the Contributor on improving their patch quality." this seems damaging to the project. perhaps merging them in newly created intentionally broken branch?

I support this but it does seem like an edge case that we should only invoke in extreme cases. We can also decide not to merge an affected PR. I see it as a loophole to accept PRs and fix them later. Maybe we should ask the ZMQ community as initial authors of the C4 for some guidance here.

1. "The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches." so when somebody makes a PR to libretime master, i'd somehow apply that PR to a personal fork in order to test it?

You can switch to their forks branch to test them, being able to maintain multiple personal forks as part of development is important.

edit: I really like (and fully support) what you are proposing as your focus !!!

[Robbt]

Cool. I think @frecuencialibre has been contributing a fair amount in terms of the project and would make a good maintainer especially one focused on the documentation as this is key for bringing on new users etc.

[hairmare]

I updated @frecuencialibre's invite to make him a Maintainer.
Thank you so much and welcome aboard 😃

[frecuencialibre]

muchas gracias compañeros!

[JohnnyC1951]

¡De nada! Estoy feliz de tener un profesional aquí;

[frecuencialibre]

I volunteer to give a hand with this...

Hi Matias!
Any thoughts on which of these pages you'd like to update?
pd. vamos a pasar por misiones en diciembre para ver a mi suegro. chiquitito el mundo. 'taria chido toparnos. saludos!

[frecuencialibre]

forgot to ping you haha @matias-tecnosoul saludos! i'll be chipping steadily away at this one, and could definitely use some help :)

[matias-tecnosoul]

I volunteer to give a hand with this...

Hola @frecuencialibre! crazy coincidence!

Any thoughts on which of these pages you'd like to update?

not sure, I was kind of waiting to have a draft or smtg to start. So if you know where to start, lets do it...

pd. vamos a pasar por misiones en diciembre para ver a mi suegro. chiquitito el mundo. 'taria chido toparnos. saludos!

sweet, let's try to meet for sure!!

[nikmartin]

I am confused about the slightly legalese wording of the C4 guidelines, so if someone would clarify, I have a pile of doc PRs to submit.

"The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches."

It's a fairly accepted practive to make any and all changes on branches created for that purpose. For example, i want to make a PR on the docs to help in the effort, I'd make a branch (in my fork of course) called 'docfixes'. Make my fixes using small atomic commits as I go, push the branch to my fork then do a PR against the issue. The maintainer would then pull my branch, test/review, merge, and delete the branch,

Does the above C4 guideline say NOT to do that?

[frecuencialibre]

great! welcome @nikmartin !

the workflow that you've described looks correct to me. my understanding of that phrase from the C4 document is that branches in our forks are to be used for the creation of PRs, but that we're not creating branches here in this main LibreTime/libretime repository - PRs should "pointed" to the master branch in this main repo. Other maintainers would know more, but i can confirm that PRs such as #608 are perfect!

[Robbt]

Yeah I think @frecuencialibre has the right interpretation. We don't want the main repo to be littered with topic branches and instead keep them on personal repos and then merge them when they are complete. I think the intention was more important for a project like ZeroMQ which the C4 was developed for but the basic idea is sound. Keep the master repo clean and merge things when they solve a specific problem. So yeah the way you did it is right. I think it's generally called the Pull & Fork approach. If multiple people want to collaborate on a feature a WIP PR is posted and people can push code to the branch on the individual repo. At least that is how we have done it thus far.

[greenjon]

1. I'm working on this a bit. At the moment I'm just changing "Airtime" to "Libretime" in the docs and that is ~50% complete.
2. When that's done & merged, I'll work on renaming the screen shots where ever they have "airtime" in the filename or filepath. I'll also take new screen shots where needed.
3. When that's done I'll go through the list here and do what I can.

[greenjon]

Systems-General can be checked off re: soundcloud + email.

[greenjon]

Media Folders can be checked off. The references to watched folders and FTP uploads have been removed.

[greenjon]

Help can be checked off. Links are now correct.

[greenjon]

Support/Feedback: this 404s and I don't see any similar doc in my repo. Should I make this doc, or should I find/remove references to it (if any) in the other docs?

[hairmare]

I recently (#673) removed Support/Feedback since it was mostly about activating the call home script on a SaaS settings page that I removed in the same go.

[zklosko]

I've lost track of everything I've added to #1014 , but I believe I've added information on Netplan, ufw, and other lists of commands to easily install LibreTime on a Ubuntu Server. I've also filled out information for the radio page and added screenshots, and merged the How-tos and Tutorials sections of the docs because they effectively repeated the same information twice. I haven't thoroughly gone through the entire site, but a significant amount has been added to allow for clarity during installation that I'm going to request that we consider merging the PR now.

Also pleased to report that LibreTime runs well on 18.04 LTS. :)

[Robbt]

Thanks so much for your contribution @zklosko it is much appreciated.

[zklosko]

@Robbt I'm happy to help!

Our station was really concerned about COVID-19's impact on us. This project seriously saved our butts. Thank you all so so much. :)

[zklosko]

I have a question: are we planning to add in the show recorder, or are we just planning to remove the documentation?

[paddatrapper]

There is a feature request for it (#42), but no one has implemented it yet. I think for the moment, we can remove the docs and leave a note that it is not supported, linking to the issue

[zklosko]

Okay. I've removed it from my PR.

[zklosko]

@Robbt It looks like Localization can be checked off

[zklosko]

Also wanted to share: I'm working on a way to get a copy of LibreTime running on Multipass, a new VM manager from Canonical for Ubuntu which is similar to Docker but smaller and much less complicated. Check out the repo here.

[zklosko]

@Robbt You can check off SSL stuff

[zklosko]

@Robbt Would it be okay with you if we embedded the widget from your station's website on Libretime.org to show what the widget can do?

[Robbt]

That is fine with me. I don't think my station would mind the additional listeners.

[zklosko]

Could you share the code with me?

[Robbt]

[zklosko]

@Robbt Could you please also send me the live code from your "Weekly Shows" widget?

[zklosko]

Also, I've been working on this more in #1101. I've been getting feedback from padda; could I also get feedback from others? Hoping to close this issue with my PR.

The one thing I'm stuck on is documentation for widgets.

[Robbt]

What do you need help with regards to the widgets ? They're just pretty much iframes that you can embed in a page to link to your other page. I guess it would be helpful to clarify for people that their libretime instance would need to be public facing to use the widgets.

[zklosko]

Guess I was just feeling lazy. Just got it finished up.

[paddatrapper]

Fixed in #1101