Difference between revisions of "Github"

From Hacksburg Wiki
Jump to navigation Jump to search
(Created page with "Hacksburg maintains a Github organization [https://github.com/Hacksburg here]. == Github == Board members should get push access to the Hacksburg repositories. For this, the...")
 
 
Line 7: Line 7:
 
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!).
 
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 work on a repository, you must first clone it by running
+
To clone the Hacksburg website's GitHub repository, run:
  
−
<file>
+
<pre>
−
git clone [url]
+
git clone https://github.com/hacksburg/hacksburg.github.io
−
</file>
+
</pre>
  
−
where [url] is the URL of the repository. This will create a subdirectory with the contents of the repository in it.
+
This will create a local copy of the remote repository on your machine (which you can then modify).
  
 
=== Github Pages ===
 
=== Github Pages ===
  
−
The Hacksburg website lives at [http://hacksburg.org hacksburg.org]. It's hosted on Github's servers (thereby taking advantage of Github's good uptime). The repository is [https://github.com/hacksburg/hacksburg.github.io here].
+
The Hacksburg website lives at [https://hacksburg.org hacksburg.org]. It's hosted on Github's servers (thereby taking advantage of Github's good uptime). The repository is [https://github.com/hacksburg/hacksburg.github.io here].
  
−
==== Posting to the Site ====
+
== Posting to the Site ==
  
−
The site is built using Jekyll, so to write a new post you will need to be added to the [https://github.com/hacksburg Hacksburg GitHub group]. Once you have access to that, clone the repository locally. Then, copy the format of one of the existing articles in the _posts/ directory, including the filename convention. Next, update the date and time  of the filename to the current date and time, and change the title to something more meaningful (Ex: ''2015-06-02-1556-post_title.markdown'').
+
The site is built automatically using [https://github.com/features/actions GitHub Actions]. Every time a pull request is merged into the master branch, [https://github.com/Hacksburg/hacksburg.github.io/blob/master/.github/workflows/build-and-upload.yaml an action] runs which executes [https://github.com/Hacksburg/hacksburg.github.io/blob/master/build.py build.py] to write posts to [https://github.com/Hacksburg/hacksburg.github.io/blob/master/index.html index.html] based on the contents of [https://github.com/Hacksburg/hacksburg.github.io/blob/master/posts.json posts.json].
  
−
Change the data in the "frontmatter" (the section between the lines containing only dashes) to match your new post, and then write the remaining article in [https://guides.github.com/features/mastering-markdown/ Markdown syntax]. When you've done that, 'git add' the file you made, 'git commit' with a message about the article you wrote, and 'git push origin master' to get github to rebuild the page.
+
To create a new post (or modify an existing one), clone [https://github.com/Hacksburg/hacksburg.github.io the repository], modify [https://github.com/Hacksburg/hacksburg.github.io/blob/master/posts.json 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 https://hacksburg.org].
  
−
If you want to include images, put them in the images/ directory and reference them in the article as "/images/[filename]".
+
=== Post Structure ===
  
−
==== Blog style ====
+
Posts, as defined in [https://github.com/Hacksburg/hacksburg.github.io/blob/master/posts.json posts.json], have the following structure:
 +
<pre>
 +
{
 +
"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
 +
}
 +
</pre>
  
−
The style of the blog uses Bootstrap to make it adaptive ('responsive'), and is based heavily on the example blog template provided on Bootstrap's home page. A number of changes have been made to this template. If you'd like to redesign or modify the design, it is probably a good idea to get acquainted with the Bootstrap documentation beforehand, as well as HTML and CSS, so you can make the changes in a sensible way.
+
The build.py script uses these variables to build index.html automatically.
 +
Post images are stored in [https://github.com/Hacksburg/hacksburg.github.io/blob/master/resources/images /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 [https://github.com/Hacksburg/hacksburg.github.io/blob/master/rss_to_json.ipynb Python notebook] is provided that scrapes [https://www.meetup.com/hacksburgva/ 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,
 +
# Modify and save your local version of <code>posts.json</code>
 +
# Run <code>build.py</code> to update <code>index.html</code>
 +
# Run <code>python -m http.server</code> (or other similar command) to initialize a local webserver
 +
# Open <code>http://localhost:8000/</code> (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:
 +
<pre>
 +
git checkout -b your-branch-name
 +
</pre>
 +
 
 +
2. Add your modified files to the staging area:
 +
<pre>
 +
git add posts.json
 +
git add resources/images/your-new-image.jpg  # if you added a new image
 +
</pre>
 +
 
 +
3. Commit your changes with a descriptive message:
 +
<pre>
 +
git commit -m "Add new post for upcoming cider making event"
 +
</pre>
 +
 
 +
4. Push your branch to GitHub:
 +
<pre>
 +
git push origin your-branch-name
 +
</pre>
 +
 
 +
5. Visit the [https://github.com/Hacksburg/hacksburg.github.io 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 [https://hacksburg.org 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 [https://github.com/Hacksburg/hacksburg.github.io/actions GitHub Actions tab] to see if there were any build failures
 +
* Verify your JSON syntax is valid using a tool like [https://jsonlint.com/ 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

Latest revision as of 11:37, 12 November 2024

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
Retrieved from "https://wiki.hacksburg.org/index.php?title=Github&oldid=1965"