Proposal: port new singlepage app to libretime repo/libretime.org and migrate docs to /docs subfolder #543
Comments
|
here's my big yes! to the new landing page and moving docs to the subdomain. good work team! i see a few additions i'd make to ned's work, but definitely a great step! |
|
This looks awesome! As an alternative to DNS changes and multiple site we could als move it to the mkdocs process that already hosts the docs and move them to The current site is being pushed by travis using this: The actual build is done with this snippet: Maybe moving the whole page from it's own repo to a new |
|
First off - Nice work @ned-kelly🥇. Couple random thoughts/followups based on what's been discussed here.
|
|
@gusaus i think hairmare's comment above is showing how that repo gets pushed to automatically by the Travis bot upon commits being made to the docs folder in the main LibreTime repo. I'm not qualified to argue the pros and cons of keeping the website within the main "monorepo" approach vs. just directly making our website updates in another repo, but would like to understand. It seems like keeping the entire site including assets etc. within the main repo may weigh it down. (due to the long history of commits a clone is already at 450mb+). Also, it would seem more efficient to not require core committers (who already have a tonne on their plates) to also have to approve css tweaks and typos on the site. |
|
Hi guys - (morning here in AU) - Let me quickly jump in... @gusaus - All the docs etc are generated by the build server that then just renders the markdown to HTML & pushes it up to the github repo that's published with github pages. @hairmare - I thought about just submitting a PR to shift the docs to a subdirectory originally, but I think it would be better longer-term to move the actual docs to a subdomain that's just dedicated to the documentation for the project and any future associated projects - We could also host RPMs etc on that sub domain and may even look at pushing it into something like S3 + Cloudfront in the future if there was more traffic to that particular site... That's just my two cents, in the end it really does not matter which way we go however I'd personally keep the docs git project just the docs, and the site just the site - I'm going to be away starting today for 1-2 weeks (so won't really be around much) so I've added you into the project @hairmare so you can take the lead and move it where-ever is the best option :) |
I plan on hosting RPMs on build.opensuse.org as they have a very usable build environment and I've actually started work on this recently (as in today).
It doesn't really matter to me as well 😉 Right now everything is in one repo, so I would lean to keeping that the same. Thanks for your confidence and the invite. I'll try to keep the ball moving while you're away. |
|
so i'm seeing two loose proposals:
Perhaps this is excessive, but my vote is that now would be a good time to separate docs, website, and libretime into 3 separate repos. I remember reading in the C4 dev process doc a few goals:
@hairmare @Robbt once up and running, would a 3 repo setup save you any time/headache? |
|
Well honestly @hairmare did most of the set-up in the first place, I have limited knowledge of Travis CI which is used to push changes and do some automated testing and that also pushes the doc page to the github site. I think that conceptually it would make sense to separate them into different repositories, but I'm not sure how much of a time saver it would be, as having the docs tracked along with the source code could make it easier to say require documentation when adding new features. If you actually go to the libretime.org you can click the link to edit the documentation and get redirected to github where you can edit it directly and create a PR. This wouldn't be the case for the site. It would just mean that there would be a new folder in our github repo (that everyone would also download when they clone it) that contains the actual site and we could edit it through git the same way we edit the rest of the code. I think having a separate repo would make sense if we had a large enough number of contributors that we needed a separate maintainers list just for the documentation but I don't think this is necessary at this point. I'm not sure and I'd defer to @ned-kelly on how much sense it would make to move the site he made into a sub-directory, it was built with this project that uses npm and gulp for advanced purposes. I think in theory it would work inside a folder of our main repo and you could modify the content directly and then commit the changes back to git. Ultimately I'm just going to suggest we defer to @hairmare at this point, because I don't know off-hand how to modify travis to do this (but could research it if needed) and I don't control the DNS that would be necessary to point it at a separate repo. I see the 3 repos as being a good idea in theory if we were a larger project that needed to delegate documentation and the site to a separate team. Since the new site is just a 1 pager and the docs are already integrated into LibreTime and thus moving them into a new repo would be a bit of work and also would either lose commit history or have to do some advanced git stuff to just pull the docs contributions into a new repo. I'd say lets just try and merge the 1 pager into the site folder and write documentation for how to update it. That's my long-winded take on this. |
|
now i've changed my mind, ;P after seeing how convenient it is to close issues with commit messages to documentation improvements, and talking with Robbt by phone, i say we keep docs here in the main repo. @Robbt i think both @hairmare and @ned-kelly have expressed that they're not stressing either way, so i'd say we just move forward with cloning https://github.com/ned-kelly/libretime-website to the LibreTime account. sound right? |
Robbt
changed the title
|
I changed the issue name to reflect what I see as the current consensus. Before we launch it'd be great if we could get the Docker stuff ported over to the LibreTime docker repo so that things are based on the LibreTime master and also get more hands-on testing. Perhaps even offer a simple docker all-in-one alternative to the more robust setup that @ned-kelly is working on. I think the steps are moving the site over are porting the new site to a /site folder via PR and then modifying Travis to build mkdocs in a docs subfolder and modify it to deploy the new single page app. |
so we're back to including the site in the main repo? this is getting frustrating as the weeks pass. |
|
I mean it doesn't really matter either way, it's just the difference between setting up a separate repo and DNS. A subdomain vs subdirectory. The DNS modifications require credentials that only @hairmare has currently. He is also the one who setup the Travis CI. I don't think it matters very much either way but in theory it would be easier to just add site and modify Travis CI. |
|
ok, i wasn't understanding that we need to do this without dns changes. so the PR simply adds https://github.com/ned-kelly/libretime-website to a another issue is that i hope to publish soon documentation (mostly vids) in spanish. not sure where the best place would be for those. they don't even have to be in libretime.org. |
|
Yeah I think that in theory we can just have mk-docs build into the /docs folder of the github static site and then modify Travis CI to point the site directory to the top directory. It looks like mkdocs doesn't support multiple languages see this issue for a discussion of it. So we would need to figure out how we want to approach internationalization of the docs, the above link connects to what read the docs and other open-source documentation efforts are doing. I think since LibreTime UI is offered in a number of different languages it would be ideal if we had a good solution for our documentation site as well but it also doesn't appear that there is a simple solution to just translate each page into multiple languages with the current setup. I think this could be put into a separate issue to discuss how we want to approach multi-lingual documentation. |
|
agreed, if internationalization is a big deal then lets cross that bridge when we come to it |
|
I'm looking at the travis ci documentation for deployment to github pages, but can't see an option to deploy to a subfolder in the target repo that we could add to the travis config i found. if it's true that this config option doesn't exist, then i'm thinking there's no way around making DNS changes. https://github.com/LibreTime/LibreTime.github.io should be the |
No need for that on travis, it's just a subfolder after all, ie. the site could get built to Some plumbing will need touching so we can get nodejs builds into the chain proper. It's like a third language and our build chain already does php and python (ie the current build and deploy are all coupled to with |
|
This issue has been automatically marked as stale because it has not had activity in the last 5 months. It will be closed if no activity occurs in the next month. |
@ned-kelly has put together a single page app at https://ned-kelly.github.io/libretime-website/ that could serve as the landing page for the project at libretime.org - we could port it over to be the main libretime.org site and move our current site to a subdomain such as docs.libretime.org - currently any DNS changes require @hairmare to implement.
We also don't have a decision making mechanism outside of Github so I'm going to suggest that for now we use github issue queues to make decisions like this that our outside of the code itself but directly related to project direction and infrastructure to enable transparency and allow people to chime in and participate.
The text was updated successfully, but these errors were encountered: