[Feature] Update README for Local Setup and Live Changes Visibility
Closed this issue · 11 comments
Problem
Description
When following the process of forking, cloning, and running the Docker command for the project, users encounter an issue where any changes made to the code are not reflected in the browser. This limitation hinders the development and testing process, as contributors cannot see real-time updates or modifications they implement in the codebase. As a result, this impacts productivity and the ability to efficiently debug and refine features.
To enhance the development experience, it is essential to provide a clear method for running the project locally, allowing developers to view their changes directly in the browser without relying solely on Docker.
Alternatives
Running Jekyll Directly: Applicants could install Ruby and Jekyll on their local machines to run the project. However, this requires additional setup steps and may lead to permission issues, as experienced during the bundler installation process. This can be aded to the Foundational Technologies page https://opensource.creativecommons.org/contributing-code/foundational-tech/ with detail instruction on how to install and set up .
Additional context
Implementation
- [ x] I would be interested in implementing this feature.
Running this project in docker should cause changes to be reflected when made? I'm not sure this is a matter for changes within the README.md, but if there are errors here it would be that either the local Docker setup of the end-user is incorrect, or the Docker setup of the project is broken.
If the actual issue is that Docker is not rebuilding the Jekyll site on change, then please either change this Issue to better reflect that with more details, or create a new Issue outlining that issue specifically.
@possumbilities After cloning the project and using docker to set up , the development
You can view the project with this url on the browser localhost:4000
But when changes is made in the editor (Vs code ) it does not reflect in the browser .
So as alternative there should be a detailed documentation to use Jekyll.
(I used jekyll and I saw changes made in vscode, reflect on my browser )
@possumbilities The issue is just to update the ReadMe file to add detailed installation and set up process using Jekyll as an alternative
Let me know if I should still do this in a new issue.
@Dev-JoyA The Docker setup should also provide reflected changes the same as a standalone Jekyll install. So I refer back to my first comment which is that this seems to be an issue with Docker (either your setup, or the project itself), not a requirement to alter the documentation itself.
This seems like you are encountering one of the following:
- an error in your local Docker setup
- an error in the project's Docker setup
Whether someone is using Docker, or just Jekyll alone, changes made to the files should reflect in the browser.
@possumbilities I didn't notice an error in my docker set up, but still i recommend an alternative set up
@Dev-JoyA You said that when you make changes when using Docker the changes are not reflected in your browser, right? That would be an error, since the changes are supposed to be reflected in that use-case.
If you are using Docker, the site should rebuild on change and show up in the browser. If it doesn't there's an error somewhere.
Thanks @possumbilities for your prompt response and feedback , I will do well to run it again using Docker.
@Dev-JoyA If you can find the error, please open another Issue targeting that specific Issue. For now I'm going to close this Issue.
Hello @possumbilities,
You’re absolutely right—it did take a long time to run, mostly due to my poor network connection at that moment, but it worked in the end.
Would it be okay to create an issue for the README file suggesting the addition of an alternative installation method using Jekyll? The README currently states: "Local development can be previewed by installing Jekyll or by using Docker. " However, only the Docker command is provided.
Let me know your thoughts!
Hello @Dev-JoyA,
I think the Jekyll Setup will be much more complicated than the straightforward Docker Setup. That's the reason we only have the Docker route listed there (in the README), as it is completely sufficient. I don't think including an additional route is a priority.
@Murdock9803 Thanks for your response and clarity.
Regards.