test pull

guides/local-git-setup.md

@@ -0,0 +1,146 @@
+# Complete Git Setup
+
+
+> This page is a work in progress. PRs welcome!<br />
+> TODO: I'm going to make instructions clearer, and add screenshots
+
+This document covers:
+- [Creating a GitHub Account](#creating-a-github-account)
+- [Installing Git](#installing-git)
+- [Setting up SSH keys](#setting-up-ssh-keys)
+- [Configuring the gitconfig](#configuring-the-gitconfig)
+
+
+## Creating a GitHub Account
+
+---
+
+## Installing Git
+
+For official installation downloads and docs, see [git-scm.com/downloads](https://git-scm.com/downloads)
+
+### Installing Git on Windows
+
+[Git for Windows](https://gitforwindows.org/) is a complete package of all the basic git tools you'll need, with an easy GUI installer.
+
+1. Download the latest executable from [the Git for Windows Releases](https://github.com/git-for-windows/git/releases)
+2. Run the installer (by double clicking on the downloaded .exe file)
+3. Follow the on-screen instructions to install git onto your machine
+4. Restart explorer.exe (so the new git executable can be found)
+5. Run `git --version` to verify that git has been installed correctly
+
+### Installing Git on Mac
+
+The easiest way to install Git on MacOS is via Homebrew.
+
+1. If you don't yet have Brew installed, install it with:
+	`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
+2. Then install git with
+	`brew install git`
+3. Finally, verify git has been installed
+	`git --version`
+
+### Installing Git on Linux
+
+On Linux, the best method for installing git is using your system's native package manager. Be sure to update your repositories first. You may need to run install commands as `sudo`
+
+- Debian / Ubuntu: `apt install git`
+- Fedora: `dnf install git`
+- OpenSUSE: `zypper install git`
+- Gentoo: `emerge --ask --verbose dev-vcs/git`
+- Arch: `pacman -S git`
+- NixOS: `nix-env -i git`
+- FreeBSD: `pkg install git`
+- OpenBSD: `pkg_add git`
+- Alpine: `apk add git`
+
+---
+
+## Setting up SSH keys
+
+
+### Intro to SSH
+
+When you push to a repo, or make any changes from your local machine, you've got two options for auth, HTTPS or SSH. With HTTPS you'll be prompted to enter a username + password each time you push, whereas with SSH you are authenticated automatically if once your key is setup.
+
+#### What is SSH Auth?
+SSH (or Secure SHell) authentication is a method used to establish a secure connection between a client and a server using cryptographic key pairs: a public key (which you share) and a private key (kept secret on your machine).
+
+#### How It Works:
+1. You generate an SSH key pair (a public key and a private key).
+2. You add the public key to GitHub (or another platform).
+3. When connecting to GitHub, it will challenge the client to prove they have the corresponding private key.
+4. Your machine uses its private key to respond correctly, verifying your identity without ever revealing the key itself.
+
+#### Benefits Over HTTPS Clone:
+- **Security**: Keys are typically more complex than passwords, making them harder to crack.
+- **Convenience**: Once set up, no need to enter a username/password with each interaction.
+- **Access Control**: Key-based authentication allows finer-grained control, like read-only or full access.
+
+#### Note for New Users:
+It's essential to keep your private key secure and never share it. If someone gains access to it, they have access to everything the key provides access to. Also, using a passphrase when generating SSH keys adds an extra layer of security.
+
+
+### Setting up SSH
+
+#### Generating an SSH key
+
+You may already have a key, in which case you can skip this step. If you do, it'll likely be in a directory named `~/.ssh/`, you can check this by running `ls -al ~/.ssh` - if you see output, and a file ending in `.pub` then you've already got a key!
+
+Otherwise, we'll generate a new key by running:
+
+```bash
+ssh-keygen -t ed25519 -C "[email protected]"
+```
+
+<details><summary>Note for legacy systems</summary>
+For legacy systems which does not support Ed25519 algorithm, use:
+
+```bash
+ssh-keygen -t rsa -b 4096 -C "[email protected]"
+```
+
+</details>
+
+When prompted, complete the form (if you choose to set a password, be sure to remember or make note of it!)
+
+Next, we should to ensure that the SSH agent is running and that the key is added to it.
+
+```
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_rsa
+```
+
+#### Adding your key to GitHub
+
+Next, we need to add the public key to your GitHub profile.
+
+Copy the contents of your newly generated SSH public key (the one ending in `.pub`). You can view the file by running `cat ~/.ssh/id_ed25519.pub` (if you named your key something else, update that accordingly)
+
+Next head over to GitHub, and log into your account
+1. Click on your profile photo, then click on Settings.
+2. In the left sidebar, click on SSH and GPG keys.
+3. Click the New SSH key button.
+4. Paste Your Key
+5. In the "Title" field, enter a descriptive label (like "My Laptop" or "Work PC").
+6. Paste your key into the "Key" field.
+7. Click the Add SSH key.
+
+
+---
+
+## Configuring the git config
+
+
+Like other applications and services, git is configurable through a dotfile. You'll likely find your git config in `~/.gitconfig` - but it can be managed using the `git config` command.
+
+Before we make our first commit, there are a few things we need to set up in the git config. We can do this by running the following commands:
+
+```bash
+git config --global user.name "Your Full Name"
+git config --global user.email "[email protected]"
+```
+
+That's all you need for now, but there are many other settings that can be tweaked here, such as setting aliases shorthands, default editor/conflict/diff programs, enabling features, using plugins, etc. It's also possible (and sometimes preferable) to have different git configurations for different projects.
+
+To learn about those, see the [Git Configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration).

guides/open-source-for-businesses.md

@@ -0,0 +1,32 @@
+
+# Open Source for Business
+
+Wish you could do more open source work at your day job?
+The following article should give you some pointers that you can use to help you explain the business benefits of open source to your company or boss.
+
+### Key Benefits 
+- Attract a higher calibre of talent
+- Improve reputation and brand recognition among development circles
+- Reflects well on you from a technological and ethical perspective
+- Great experience for junior developers to contribute and learn
+- Opportunity to showcase and share your tech standards
+- Cost saving potential, as once a project is off the ground, external contributors often do the bulk of maintenance and improvements
+- Helps you innovate quicker, the open source code and content tends to move a lot faster than corporate and propriety alternatives
+
+### Key Disadvantages / Considerations
+- Comprehensive review process needs to be in place, to ensure that any content you put out is correct, ethical and able to be shared publicly
+- Time constraints - This will take a bit of time to get setup and going
+
+### Case Studies
+- [GCHQ](https://github.com/gchq) - They've made a number of their internal tools open source (like the famous [CyberChef](https://github.com/gchq/CyberChef)), now the majority of maintenance is done by the community
+- [ElseWhen](https://github.com/elsewhencode/) - A small digital consultancy, which published [project-guidelines](https://github.com/elsewhencode/project-guidelines) helping them get a reputation for good coding standards
+- [Novu](https://novu.co/) - They [write great posts](https://dev.to/novu) on dev.to, to share knowledge
+- [React](https://github.com/facebook/react) - Started by Facebook, React.JS has now seen over 1000 community contributors, helping with bug fixes, docs and feature development
+- RedHat - A multinational company who open source the majority of their offerings, were valued at $34b (by IBM, as of 2019)
+
+### Methods
+- A GitHub organisation where employees can collate and share public components, utils and knowledge
+- By sponsoring existing projects, which are either up and coming, or that you rely upon to do our job
+- By contributing to existing projects, when the opportunity to do so arises
+- Writing blog posts on a developer-focused site, like Dev.to
+

guides/submit-your-first-pr-cli.md

@@ -0,0 +1,104 @@
+# Submit your first PR (Terminal)
+
+> This page is a work in progress. PRs welcome!<br />
+> TODO: I'm going to make instructions clearer, and add screenshots
+
+
+### 1. Fork the Repository
+
+- Start by visiting the GitHub page of the repository you wish to contribute to.
+- In the top-right corner of the page, click the "Fork" button. This will create a copy of the repository under your GitHub account.
+
+### 2. Clone Your Forked Repository
+
+- On your forked repository's main page, click the green "Code" button. Copy the URL provided.
+- Open your terminal or command prompt and navigate to the directory where you want to clone the repository.
+   Enter:
+
+```bash
+git clone [URL you copied]
+```
+
+This will create a local copy of your forked repository on your machine.
+
+
+### 3. Navigate to the Repository's Directory
+
+Enter:
+
+```bash
+cd [repository-name]
+```
+
+### 4. Set Upstream Remote
+
+To keep track of the original repository (often called the "upstream"), enter:
+
+```bash
+git remote add upstream [original repository's URL]
+```
+
+### 5. Create a New Branch
+
+Always make changes in a new branch instead of directly on main or master. To create and switch to a new branch, enter:
+
+```bash
+git checkout -b [branch-name]
+```
+
+Choose a descriptive branch name related to the changes you're planning to make.
+
+### 6. Make Your Changes
+
+Edit, add, or remove files as needed using your preferred text editor or IDE.
+
+### 7. Stage and Commit Changes
+
+Stage your changes with:
+
+```bash
+git add .
+```
+
+Commit your changes with a descriptive message:
+
+```bash
+git commit -m "Brief description of changes made"
+```
+
+### 8. Push Changes to Your Fork
+
+Push your changes to your forked repository on GitHub:
+
+```bash
+git push origin [branch-name]
+```
+
+### 9. Open a Pull Request (PR)
+
+- Go back to your forked repository on GitHub.
+- Click the "New pull request" button (often GitHub will also present a quick link to create a PR from your recently pushed branch).
+- Ensure the base repository is the original repository you want to contribute to, and the head repository is your fork. Also, make sure the branch shown for your fork is the one you just pushed.
+- Fill in the PR title and description, detailing your changes and the reason for them.
+- Click "Create pull request".
+
+### 10. Await Feedback
+
+- The maintainers of the original repository will review your PR.
+- They might request some changes. If they do, repeat steps 6-8, and the PR will automatically update with your new changes.
+- Engage in any discussions, answer questions, and make necessary changes as needed.
+
+### 11. Keep Your Fork Synced
+
+Before starting new work, it's a good practice to fetch and merge changes from the upstream (original) repository:
+
+```bash
+git checkout main
+git fetch upstream
+git merge upstream/main
+git push origin main
+```
+
+### 12. Celebrate!
+
+Once your PR is merged, you've made a successful contribution!

guides/submit-your-first-pr-ui.md

@@ -0,0 +1,43 @@
+# Submit your first PR (UI)
+
+> This page is a work in progress. PRs welcome!<br />
+> TODO: I'm going to make instructions clearer, and add screenshots
+
+### 1. Fork the Repository
+
+- Start by visiting the GitHub page of the repository you want to contribute to.
+- In the top-right corner of the page, you'll see a button labeled "Fork". Click it.
+- This creates a copy of the repository under your GitHub account. You'll be redirected to your fork.
+
+
+### 2. Make Changes
+
+- Browse through the repository files and directories by clicking on them.
+- Once you've located the file, click on it to view its contents.
+- Click on the pencil icon (it'll be labeled "Edit this file" when you hover over it) in the top-right corner of the file viewer.
+- Make your changes to the file in the editor that appears.
+
+### 3. Commit the Changes
+
+- Scroll down to the bottom of the page. You'll see a section titled "Commit changes".
+- Enter a short, descriptive title for your changes in the "Commit changes" box.
+- Optionally, provide a more detailed description in the larger text box below.
+- Ensure the radio button "Create a new branch for this commit and start a pull request." is selected.
+- Click on the green "Commit changes" button.
+
+### 4. Open a Pull Request (PR)
+
+- After committing, you'll be taken to a new page titled "Open a pull request".
+- GitHub will automatically fill in some details for the PR based on your commit message.
+- If you want, edit the title and description of the PR to provide more context or information about your changes. The more detailed and clear you are, the easier it will be for the maintainers.
+- Once you're ready, click on the green "Create pull request" button.
+
+### 5. Await Feedback
+
+- The maintainers of the original repository will be notified of your pull request.
+- They might provide feedback or ask for changes. Make sure to keep an eye on the PR for any comments or notifications.
+- If changes are requested, you can make them directly in your forked repo through the GitHub UI, and they will automatically be added to the open PR.
+
+### 6. Celebrate!
+
+- Once your pull request is approved and merged, you've officially contributed to the project!

guides/why-open-source.md

@@ -0,0 +1,69 @@
+# *Why Open Source Matters*
+
+*Open source software* refers to software whose source code is made freely available to the public. It's not just about the code; it encompasses a set of principles and practices that promote collaboration, transparency, and accessibility. 🌐🚀
+
+## Collaborative Power 🤝👥
+
+| **Key Benefits**            | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Diverse Collaboration       | Open source projects thrive on collaboration. Developers, designers, and enthusiasts from around the world come together to contribute their skills and expertise. |
+| Innovation Catalyst         | This collaborative spirit leads to innovative solutions that may not have been possible in isolated environments. Different perspectives drive creative problem-solving. |
+
+## Transparency and Trust 🔍✅
+
+| **Key Features**            | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Code Review                 | Transparency is a core principle of open source. Anyone can review the source code, ensuring it's secure, reliable, and aligned with its stated purpose. |
+| Building Trust              | This transparency builds trust among users and contributors. Knowing that code is open to scrutiny instills confidence. |
+
+## Learning and Skill Development 📚👨‍🎓
+
+| **Advantages**              | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Hands-On Learning           | Open source serves as an invaluable educational resource. Developers can study the code, learn best practices, and enhance their skills through hands-on experience. |
+| Community Mentorship        | The open source community often provides mentorship and guidance to newcomers, fostering a culture of continuous learning. |
+
+## Cost Reduction 💰📉
+
+| **Benefits**                | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Economic Benefits           | Organizations can significantly reduce their software development costs by leveraging open source solutions. Instead of building from scratch, they can build upon existing projects, saving time and financial resources. |
+| Resource Optimization       | Cost savings extend beyond development. Organizations can allocate resources to other critical areas while benefiting from high-quality open source tools. |
+
+## Innovation and Rapid Development 🚀🔬
+
+| **Advantages**              | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Accelerated Development     | Open source accelerates the pace of software development. Developers can build upon existing projects, leveraging the collective knowledge of the community. |
+| Fast Iteration              | Rapid development cycles allow for quick iterations and feature enhancements, resulting in the creation of innovative solutions. |
+
+## Accessibility and Inclusivity 🌍🌈
+
+| **Benefits**                | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Universal Access            | Open source software is often free to use, making it accessible to a diverse global audience, regardless of financial constraints. |
+| Inclusive Development       | The open source community welcomes contributors from various backgrounds, promoting inclusivity and diversity in technology. |
+
+## Longevity and Sustainability 🕰️🌱
+
+| **Advantages**              | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Sustainability              | Open source projects have the potential to thrive for years or even decades. This sustainability is made possible through the support of a dedicated community of contributors. |
+| Community Commitment        | A strong community is invested in the project's success, ensuring its longevity and continuous improvement. |
+
+## Customization and Flexibility 🛠️🧩
+
+| **Benefits**                | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Tailored Solutions          | Organizations can customize open source software to meet their specific needs and requirements, ensuring that the software aligns perfectly with their goals. |
+| Flexible Workflows          | The flexibility of open source tools allows organizations to adapt and optimize their workflows for maximum efficiency. |
+
+## Ethical and Philosophical Considerations 🌟📜
+
+| **Aspects**                 | **Description**                                               |
+|-----------------------------|---------------------------------------------------------------|
+| Values and Principles       | Open source embodies ethical and philosophical values such as openness, freedom, and sharing for the greater good. |
+| Alignment with Principles   | Some individuals and organizations are drawn to open source not only for its practical benefits but also because it aligns with their principles and beliefs. |
+
+In conclusion, open source is a powerful force in the world of technology, promoting collaboration, transparency, and innovation. It offers numerous advantages, from cost reduction to educational opportunities, and contributes to a global community that shares a common passion for creating and improving software. 🌍👏
+