Github

Hacksburg maintains a Github organization here.

Github

Board members should get push access to the Hacksburg repositories. For this, they will need to make a Github account (if they don't have one already). Members pushing to repos should use Git or some UI equivalent (eg, TortoiseGit for Windows).

A full Git tutorial is beyond the scope of this document, but in general, here's how you do things with regular command-line Git (TortoiseGit and other GUI-based Git clients will be different!).

To clone the Hacksburg website's GitHub repository, run:

git clone https://github.com/hacksburg/hacksburg.github.io

This will create a local copy of the remote repository on your machine (which you can then modify).

Github Pages

The Hacksburg website lives at hacksburg.org. It's hosted on Github's servers (thereby taking advantage of Github's good uptime). The repository is here.

Posting to the Site

The site is built automatically using GitHub Actions. Every time a pull request is merged into the master branch, an action runs which executes build.py to write posts to index.html based on the contents of posts.json.

To create a new post (or modify an existing one), clone the repository, modify posts.json, and create a pull request. Once your pull request is merged, the action will run and your post(s) will be live at https://hacksburg.org.

Post Structure

Posts, as defined in posts.json, have the following structure:

{
	"title": "Tenth Annual Hacksburg Cider Making",
	"subtitle": "Fresh, all-natural, and delicious!",
	"description": "<p>Come to Hacksburg with apples and you'll be able to make your own cider! The best kind of apples to bring is a variety, only using one type typically results in extremely sweet or tart cider. Ten pounds of apples makes three quarts of cider. Free to anyone in the community, no RSVP required.</p><p>Want more information? We go into the cidermaking process in detail here: <a href=\"https://hb.gy/0nAyF\" target=\"_blank\">https://hb.gy/0nAyF</a>.</p><p>Cider making is for attendees of all ages. If you are bringing an attendee under 18, you (the parent/guardian) must stay the whole time your child/dependent is there.</p>",
	"date": "2024-10-20",
	"start_time": "1:00pm",
	"end_time": "4:00pm",
	"offsite_location": null,
	"offered_online": false,
	"offered_in_person": true,
	"member_price": 0,
	"non_member_price": 0,
	"image": "2018_cidermaking.jpg",
	"meetup_link": "https://www.meetup.com/hacksburgva/events/302852557/",
	"cancelled": false
}

The build.py script uses these variables to build index.html automatically. Post images are stored in /resources/images. You can reference an existing image in your post, or add a new one.

Building Posts Automatically from Meetup Data

For your convenience, a Python notebook is provided that scrapes Hacksburg's Meetup page to generate posts in the posts.json format. Note: For this script to work, you must be logged into Meetup. It is recommended that you preview your post(s) before creating a new pull request.

Previewing Posts

To preview your post(s) locally,

1. Modify and save your local version of posts.json
2. Run build.py to update index.html
3. Run python -m http.server (or other similar command) to initialize a local webserver
4. Open http://localhost:8000/ (or similar) in your web browser to preview your changes

Creating a Pull Request

To create a pull request, follow these steps:

1. Create and switch to a new branch for your changes:

git checkout -b your-branch-name

2. Add your modified files to the staging area:

git add posts.json
git add resources/images/your-new-image.jpg  # if you added a new image

3. Commit your changes with a descriptive message:

git commit -m "Add new post for upcoming cider making event"

4. Push your branch to GitHub:

git push origin your-branch-name

5. Visit the Hacksburg website repository on GitHub

6. You should see a prompt to "Compare & pull request" for your recently pushed branch. Click it.

7. Fill out the pull request form:

• Give your PR a descriptive title
• Add any relevant details in the description
• Request review from another board member if needed

8. Click "Create pull request"

Once your pull request is approved and merged, GitHub Actions will automatically rebuild the site with your changes. Your new post should appear on hacksburg.org within a few minutes.

Best Practices

• Always preview your changes locally before creating a pull request
• Use clear, descriptive commit messages
• Include any relevant context in your pull request description
• Make sure images are appropriately sized and optimized before adding them
• Double-check dates, times, and links in your posts
• If you're unsure about any changes, ask another board member to review them

Troubleshooting

If you encounter issues:

• Check the GitHub Actions tab to see if there were any build failures
• Verify your JSON syntax is valid using a tool like JSONLint
• Ensure all required fields in posts.json are properly filled out
• Make sure any new images are committed to the repository
• If you need help, reach out to a board member for assistance