Create documentation for how to run our site with jekyll

[jbubar]

trafficstars

Overview

Sometimes docker does not work, so we should have some documentation about how to use jekyll.

Action Items

• [ ] We are currently in the process of moving the old wiki to the new website-wiki repo, so we will not be making any changes or additions to the old wiki at this time. Thus, we will be adding wiki content through a different process now. Please read How to Contribute to the Wiki
• [ ] create a wiki article with the necessary steps
• [ ] test it out
• [ ] Make sure it is compatible with all systems (Mac, Windows, Iinux)
• [ ] share with dev team and have people review it
• [ ] close this issue

Plan

• Create a Gemfile.example (Gemfile is in .gitignore. See comments below for discussions about Gemfile and why it can't be checked in)
• create separate markdown on deploying in jekyll. Indicate in the document that if you run into issues, support may be limited and you may be asked to try Docker.
• Link to this file from contributing.md with same caveat as above.

Instruction

• downloading ruby and jekyll for windows
• other instructions for mac
• cd into directory w website repo
• cp Gemfile.example Gemfile
• type bundle install
• type jekyll serve

[jbubar]

@cnk @akibrhast do we need a Gemfile? and also, are there any flags to add to the jekyll serve command that would be useful?

[cnk]

To run Jekyll without Docker, one would need a Gemfile. The problem is, if there is a Gemfile in the repository, it interferers with the built in Gemfile in the Docker container.

Since the important thing is that our code match what GitHub is going to do with our files once pushed, I have been reluctant to do anything other than use the prebuilt, already working, Docker container. If you still want to be able to set up the HackForLA website project not to need Docker, I recommend storing a Gemfile.example in the repo - or in the wiki. That should hide it from GitHub pages. AND make sure you match supported versions of Jekyll. GH pages does not run the latest version of Jekyll - 3.9.0 NOT Jekyll 4. https://pages.github.com/versions/

[Sihemgourou]

@jbubar please add a role label to this and remove the role missing label. Thanks !

[github-actions[bot]]

@ Please add update

1. Progress
2. Blockers
3. Availability
4. ETA

[abuna1985]

@jbubar What would you like to discuss about this issue?

[github-actions[bot]]

Hi @AzaniaBG, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[AzaniaBG]

ETA: 09/28/2022 by 5 PM Availability: 09/26/2022 3 - 4 PM; 09/27/2022 2 - 4 PM; 09/28/2022 2 - 4 PM

[ExperimentsInHonesty]

This was on an agenda 2022-10-02

Azania Baker-Garcia's issues https://github.com/hackforla/website/issues/1674 do we want a note about prioritizing using docker/discouraging people from using Jekyll Bonnie: Ethan had an issue with Docker (took a long time), figured out how to run Jeykll without docker -not a high priority until it is We should talk to Ethan about how to walk through it. https://github.com/hackforla/website/issues/2607#issuecomment-1264726733

It then got moved to the icebox. But it has no dependency, so cannot stay in the icebox. Once you add a dependency to the top of the issue and a dependency label, it can go back into the icebox.

[AzaniaBG]

I think website leads (@kathrynsilvaconway, @blulady) were trying to figure out whether it should be an issue at all...

[blulady]

This was on an agenda 2022-10-02

Azania Baker-Garcia's issues #1674 do we want a note about prioritizing using docker/discouraging people from using Jekyll Bonnie: Ethan had an issue with Docker (took a long time), figured out how to run Jeykll without docker -not a high priority until it is We should talk to Ethan about how to walk through it. #2607 (comment)

It then got moved to the icebox. But it has no dependency, so cannot stay in the icebox. Once you add a dependency to the top of the issue and a dependency label, it can go back into the icebox.

I reached out to @ethanstrominger and he told me I was mistaken, that he didn't have any issues with docker. Is there another Ethan who might have had this issue?

[AzaniaBG]

This was on an agenda 2022-10-02

Azania Baker-Garcia's issues #1674 do we want a note about prioritizing using docker/discouraging people from using Jekyll Bonnie: Ethan had an issue with Docker (took a long time), figured out how to run Jeykll without docker -not a high priority until it is We should talk to Ethan about how to walk through it. #2607 (comment)

It then got moved to the icebox. But it has no dependency, so cannot stay in the icebox. Once you add a dependency to the top of the issue and a dependency label, it can go back into the icebox.

I reached out to @ethanstrominger and he told me I was mistaken, that he didn't have any issues with docker. Is there another Ethan who might have had this issue?

That is the same Ethan I spoke with @blulady. I was under the same impression, but perhaps it was just easier for him to use Jekyll?

[ExperimentsInHonesty]

I think it's worth making if someone want to, and we are short of issues that are frontend OR backend AND medium. It's possible no one will ever need it, but that's why it has the milestone it does.

Most problems that this solution would address are already addressed in https://github.com/hackforla/website/blob/gh-pages/CONTRIBUTING.md#i-what-if-you-cannot-see-your-changes-locally-within-docker

But if you are reading this and want to work on it, jump on it!

[github-actions[bot]]

Hi @ethanstrominger, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:- i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?) ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[blulady]

@ExperimentsInHonesty Ethan Strominger 1:50 PM Aziana - See thread below, followed by a summary Hey Ethan, do you think that your experience would allow you to complete this issue? Ethan Strominger [7:12 AM] Yes. However, I had volunteered to document Jekyll earlier and Aziana, Bonnie, and others suggested documenting how to use Jekyll was not a good idea. Docker is an adequate solution and documenting how to use Jekyll could result in devs asking for support in doing this when they run into a problem - better if they have to support only one method of deploying and Docker is more foolproof. (edited) [7:14 AM] So, maybe close this as not an issue? [7:15 AM] I could add a note into the documentation that you can try to run in Jekyll without any instructions but you are on your own if you do - this way someone won’t suggest the issue in the future. [7:19 AM] I just saw Bonnie’s last comment that it could be worth it - I would want to check with Aziana and Bonnie again - in the meeting I had with Bonnie, she agreed with the above argument for not documenting it. (edited)

[ethanstrominger]

Plan:

• Create a separate markdown on deploying in jekyll. Indicate in the document that if you run into issues, support may be limited and you may be asked to try Docker.

• Link to this file from contributing.md with same caveat as above.

[ExperimentsInHonesty]

@ethanstrominger If you are still working on this, it should be in the in progress column. If you are working on another issue and plan to pick this one up later, please let us know if it has any dependencies (like a different issue HAS to be completed before this can be worked on).

[JessicaLucindaCheng]

@ethanstrominger We are currently in the process of moving the old wiki to the new website-wiki repo, so we will not be making any changes or additions to the old wiki at this time. Thus, we will be adding wiki content through a different process now. Please read How to Contribute to the Wiki

[github-actions[bot]]

@ethanstrominger

Please add update using the below template (even if you have a pull request). Afterwards, remove the '2 weeks inactive' label and add the 'Status: Updated' label.

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures (optional): "Add any pictures of the visual changes made to the site so far."

If you need help, be sure to either: 1) place your issue in the Questions/In Review column of the Project Board and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel. Please note that including your questions in the issue comments- along with screenshots, if applicable- will help us to help you. Here and here are examples of well-formed questions.

_{You are receiving this comment because your last comment was before Tuesday, July 30, 2024 at 12:05 AM PST.}

[github-actions[bot]]

@ethanstrominger

Please add update using the below template (even if you have a pull request). Afterwards, remove the '2 weeks inactive' label and add the 'Status: Updated' label.

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures (optional): "Add any pictures of the visual changes made to the site so far."

If you need help, be sure to either: 1) place your issue in the Questions/In Review column of the Project Board and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel. Please note that including your questions in the issue comments- along with screenshots, if applicable- will help us to help you. Here and here are examples of well-formed questions.

_{You are receiving this comment because your last comment was before Tuesday, August 6, 2024 at 12:04 AM PST.}