diff --git a/.devcontainer/devcontainer-lock.json b/.devcontainer/devcontainer-lock.json new file mode 100644 index 0000000..7f98514 --- /dev/null +++ b/.devcontainer/devcontainer-lock.json @@ -0,0 +1,14 @@ +{ + "features": { + "ghcr.io/devcontainers/features/github-cli:1.0.15": { + "version": "1.0.15", + "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:1ad1ec1a806cc9926c84ca5b147427bba03b97e14e91f9df89af83726039ecaf", + "integrity": "sha256:1ad1ec1a806cc9926c84ca5b147427bba03b97e14e91f9df89af83726039ecaf" + }, + "ghcr.io/devcontainers/features/ruby:1.3.2": { + "version": "1.3.2", + "resolved": "ghcr.io/devcontainers/features/ruby@sha256:1c9bbde293ba6f21449a58be34a358ffa2b3846f31cb3146409b26ab3f13e1a2", + "integrity": "sha256:1c9bbde293ba6f21449a58be34a358ffa2b3846f31cb3146409b26ab3f13e1a2" + } + } +} \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..66be5fc --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,26 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/ruby +{ + "name": "All Hands Active Site -- Ruby", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/base:debian", + // Features to add to the dev container. More info: https://containers.dev/features. + "features": { + "ghcr.io/devcontainers/features/ruby:1.3.2": { + "version": "3.2.2" + }, + "ghcr.io/devcontainers/features/github-cli:1.0.15": {} + }, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "bundle install" + + // Configure tool-specific properties. + // "customizations": {}, + + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} diff --git a/.tool-versions b/.tool-versions new file mode 100644 index 0000000..f2a971a --- /dev/null +++ b/.tool-versions @@ -0,0 +1 @@ +ruby 3.2.2 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..437f1e2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,122 @@ +# Contributing + +Welcome to All Hands Active's source code for our website! + +This document will help teach you how to contribute to our website. +Thank you for helping us make our website better! + +- [Contributing](#contributing) + - [Installing dependencies](#installing-dependencies) + - [Using a dev container](#using-a-dev-container) + - [Manual Installation](#manual-installation) + - [Installing Ruby](#installing-ruby) + - [Installing without asdf](#installing-without-asdf) + - [Installing ruby gems](#installing-ruby-gems) + - [Running the site](#running-the-site) + - [Making changes](#making-changes) + - [Pushing changes upstream](#pushing-changes-upstream) + - [Thanks for contributing](#thanks-for-contributing) + +## Installing dependencies + +> [!Warning] +> If you are on Fedora 42, there are issues conflicting with Ruby and compiling gems with native extensions. One possible workaround is to downgrade your C compiler. Another alternative is to use dev containers. +> +> See for more information. + +### Using a dev container + +We have a [dev container](https://containers.dev/) configured in order to make contributing easier. If you have an [editor that supports dev containers](https://containers.dev/supporting#editors), you can simply start up our container to automatically enter an environment with all dependencies. + +The source code and configuration for our devcontainer is located in [.devcontainer](.devcontainer). + +Please note this option requires Docker to be installed and running. + +Once the dev container is up and running, you can skip ahead to running the site. + +### Manual Installation + +#### Installing Ruby + +We recommend one of the toolchain managers, like `asdf`, `mise`, `RVM`, or `rbenv`. + +`asdf` and `mise` are useful for managing multiple toolchains, such as Javascript, Python, and Ruby, whereas `RVM` and `rbenv` manage _only_ Ruby installations. + +If you do not already have `asdf` installed, go ahead and do so. Then return to this guide. + +1\. Add the ruby plugin to `asdf`. + +```sh +asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git +``` + +2\. Install ruby. + +```sh +asdf install +``` + +##### Installing without asdf + +See [the official ruby documentation](https://www.ruby-lang.org/en/documentation/installation/) for the best ways to install Ruby. + +> [!NOTE] +> Whichever method you pick, make sure you install ruby **3.2.2**. +> This is the version we use for building our website. This is why we recommend using a version manager such as `asdf` or `RVM` + +#### Installing ruby gems + +Now that our Ruby installation exists, we can use `bundle` to install our ruby gems. + +```sh +bundle install +``` + +If this command errors out, check that you have a valid `gcc` compiler on your path, and install one if you don't. + +## Running the site + +Now that our dev environment has our dependencies installed, we can go ahead and start up the jekyll dev server. + +```sh +bundle exec jekyll serve +``` + +This will start a jekyll development server which will watch for any edits to our website, and automatically reload the backend. + +Please note that jekyll will not automatically reload the frontend, so you'll need to manually refresh the browser to see any changes. + +## Making changes + +> [!Warning] +> +> BEFORE starting work on an issue, please make sure that there is an open issue for your change, and that someone else is not already working on it. +> We hate seeing contributions go to waste as multiple people were working on it. +> +> Please comment on an issue letting us know you want to work on it before starting work on it! + +> [!Tip] +> If you are new to using GitHub and Git in general, check out the guides on Github that explain how to use Git and work with others on projects using Git! +> +> + +If this is your first time contributing to our website, [create a fork](https://github.com/allhandsactive/site/fork) before making any changes. This is where you will push your commits. + +Next, create a new branch with + +```sh +git branch -c +``` + +Try to name it something descriptive, like a branch for creating a contributing document would be named feat/add-contributing.md + + +### Pushing changes upstream + +When you are satisfied with your changes, commit to a new branch (not the master branch!) and push it to a fork on GitHub. + +From there, [create a pull request](https://github.com/allhandsactive/site/pull/new) and fill out the form there. + +## Thanks for contributing + +If you encounter any issues setting up an enviroment or have any questions, please let us know by [opening an issue](https://github.com/allhandsactive/site/issues/new). diff --git a/README.md b/README.md index f4f9deb..962f9c6 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ # Site -Jekyll Site for AHA. -## Theme -Site built with the Minimal Mistakes theme. [Documentation](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/) +Jekyll Site for All Hands Active, a community-ran makerspace serving the community for over 15 years. -## Local testing -To test the site locally, run `bundle exec jekyll serve` and navigate to `localhost:4000`. +## About + +This site is built with ruby and jekyll, and is publicly avaiable at , + +We're using the [Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/) theme for the majority of our website. + +## Contributing + +If you are interested in contributing, please see [CONTRIBUTING](./CONTRIBUTING.md).