New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Problem: The documentation is out of date #376

Open
Robbt opened this Issue Dec 1, 2017 · 15 comments

Comments

Projects
None yet
6 participants
@Robbt
Copy link
Member

Robbt commented Dec 1, 2017

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

  • Features - is all TBD
  • On The Air in 60 seconds - needs instructions refined for LibreTime
  • GettingStarted - remove info about Registering since we don't do that - and need to update Image assets w/ new screenshots thanks @nikmartin
  • Systems-General - refers to settings that don't exist like Soundcloud and e-mail settings - how do we handle e-mail w/ LibreTime ?
  • Users - needs updated screenshots
  • Media Folders - this functionality doesn't exist in LibreTime should be at least updated w/ a notice and link to PR
  • Stream Settings - at least need to update and remove Scheduled Play as we don't have that feature
  • Support/Feedback - put info about Fork and links to Github and discourse forum vs. referring to SourceFabric
  • Now Playling - needs new screenshots
  • Add Media - needs new screenshots for new UI
  • Library - needs info on Auto Playlists and smartblock updates (maybe should be easier for find Smart Blocks and Web Streams from main menu vs. hidden under Library
  • Calendar - UPDATED - could use a little bit more info on automatic playlists
  • Listen - probably ok but could use new screenshots
  • Help - needs links to LibreTime
  • Recording - currently not supported by LibreTime - needs info regarding this
  • Install - should refer to ./install -fiap for most purposes
  • Preparing Server - need to remove reference to system / and debian squeeze as we don't support that. Possibly add info regarding distro etc.
  • Automated Installation - we haven't done this - so should remove it from the page or link to issues regarding it
  • Manual Install - no different than Install but has outdated info regarding 2.5.1
  • Airtime Log - 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.
  • Airtime Backup - mostly OK
  • Upgrading - this needs updated w/ LibreTime specific information
  • TroubleShooting - needs info regarding systemd and upstart specific restart commands and how to access the logs
  • Monit - test or remove for now as we haven't supported it
  • Automated File Import - needs updating because it isn't supported at the moment
  • Player on Website - should update w/ widget
  • Export schedule - test API info and also add widget instructions
  • 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
  • Localization - refer to the Zanata translation webpage not SourceFabric
  • SSL stuff - maybe add info on Let's Encrypt etc
  • Expert install - all outdated info here
  • Autoloading Playlists needs new screenshot, explanation with a video

Stuff missing from Manual

  • * Podcasts
  • * Changing Icecast passwords
  • * Embedding Widgets

@Robbt Robbt changed the title Problem: The documentation is outdate and has incorrect info and screenshots Problem: The documentation is out of date Dec 1, 2017

@matias-tecnosoul

This comment has been minimized.

Copy link

matias-tecnosoul commented Sep 5, 2018

I volunteer to give a hand with this...

@frecuencialibre

This comment has been minimized.

Copy link
Contributor

frecuencialibre commented Oct 13, 2018

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

This comment has been minimized.

Copy link
Member

hairmare commented Oct 13, 2018

@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

This comment has been minimized.

Copy link
Contributor

frecuencialibre commented Oct 13, 2018

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 #249 #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

This comment has been minimized.

Copy link
Member

hairmare commented Oct 13, 2018

  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

This comment has been minimized.

Copy link
Member

Robbt commented Oct 14, 2018

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

This comment has been minimized.

Copy link
Member

hairmare commented Oct 14, 2018

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

@frecuencialibre

This comment has been minimized.

Copy link
Contributor

frecuencialibre commented Oct 14, 2018

muchas gracias compañeros!

@JohnnyC1951

This comment has been minimized.

Copy link

JohnnyC1951 commented Oct 14, 2018

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

@frecuencialibre frecuencialibre self-assigned this Oct 15, 2018

@frecuencialibre

This comment has been minimized.

Copy link
Contributor

frecuencialibre commented Oct 15, 2018

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

This comment has been minimized.

Copy link
Contributor

frecuencialibre commented Oct 23, 2018

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

This comment has been minimized.

Copy link

matias-tecnosoul commented Oct 24, 2018

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 added a commit to nikmartin/libretime that referenced this issue Nov 25, 2018

Replace Airtime with LibreTime
Line breaks at 120ish columns
Fixes checkbox 2 of LibreTime#376
@nikmartin

This comment has been minimized.

Copy link
Contributor

nikmartin commented Nov 25, 2018

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

This comment has been minimized.

Copy link
Contributor

frecuencialibre commented Nov 25, 2018

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

This comment has been minimized.

Copy link
Member

Robbt commented Nov 25, 2018

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.

@Robbt Robbt added this to the 3.0.0 milestone Jan 18, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment