diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 9db07700b..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,23 +0,0 @@ -# Contributing to the Raspberry Pi PCIe Database - -Testers welcome! - -There are many ways to contribute: - - 1. I accept cards mailed to me, and may be able to pay shipping. I can't promise to test the card in a timely fashion, but I will try to, and I will credit you in any videos/posts that result from card testing! - 2. If you find any typos, incorrect links or images, or other issues, please submit a PR to fix it! - 3. If you want to test a card on your own, I'm happy to add it to the database, provided you give all the testing details, information like `lspci` and `dmesg` logs, etc. in a GitHub issue, and follow the project's conventions for card details. - -## Adding a Card - -Add a file named after the card into the appropriate `_cards_[type]` directory. Copy the template out of [`card-template.md`](card-template.md) into this new file. - -Add a picture of the card into the `images/` directory, prefixed by `[type]-`, and make sure to reference the full path to the image in the `picture` frontmatter on the card post. - -For example, for a network card: - - 1. Make sure there's a GitHub issue that exists for the card. - 2. Copy the template into a new file inside `_cards_network`. - 3. Fill in the details of the card. - 4. Put a picture of the card named `network-[name-of-card].jpg` inside `images/`. - 5. File a PR with your changes. diff --git a/README.md b/README.md index 1b78edad7..0ec18b7b9 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,98 @@ -# Raspberry Pi PCI Express device compatibility database +# Raspberry Pi PCIe Devices -This repository builds the GitHub pages site: [http://pipci.jeffgeerling.com](http://pipci.jeffgeerling.com) + +![GitHub repo size](https://img.shields.io/github/repo-size/geerlingguy/raspberry-pi-pcie-devices) +![GitHub last commit](https://img.shields.io/github/last-commit/geerlingguy/raspberry-pi-pcie-devices) +![GitHub stars](https://img.shields.io/github/stars/geerlingguy/raspberry-pi-pcie-devices?style=social) +[![Sponsors](https://img.shields.io/github/sponsors/geerlingguy)](https://github.com/sponsors/geerlingguy#sponsors) +![license](https://img.shields.io/github/license/geerlingguy/raspberry-pi-pcie-devices?logoColor=blue) -If you would like to add a new device to the site, or correct the information about an existing device, please file a Pull Request against this repository. +[**Raspberry Pi PCIe Devices**](https://pipci.jeffgeerling.com/) is a compatibility database that tracks which devices are and are not compatible with the [Raspberry Pi CM4](https://www.raspberrypi.com/products/compute-module-4/). -## Local Editing +

+ CM4 IO Board PCIe Slot +

-This site uses Jekyll to build and serve pages. On a local workstation, clone the repository, make sure you have Ruby, Bundler, and Jekyll installed, then run `jekyll serve`. +# Setup and installation -Access the local site at the address Jekyll provides. +To run a copy of this website in a local web development environment, you need to have **Jekyll**, **GitHub CLI** *OR* **GitHub Desktop**, and a local clone of the website's repository. + +### Jekyll +This site is built using [Jekyll](https://jekyllrb.com/), a [Ruby](https://www.ruby-lang.org/en/) gem. + +**To install Jekyll:** +1. Visit Jekyll's [installation page](https://jekyllrb.com/docs/installation/) in your browser +2. Click the guide for your operating system (macOS, Ubuntu, Other Linux, or Windows) +3. Follow the step-by-step instructions to install Jekyll. + +### GitHub +There are two ways to use GitHub locally: +* via [GitHub CLI](https://cli.github.com/), using the command line +* via [GitHub Desktop](https://desktop.github.com/), an app available for macOS and Windows + +# Contributing + +## Ways to contribute: +* **Add a card or board to the list:** Use issues and pull requests to add new board entries and card entries to the site. +* **Test a card yourself:** If you want to test a card on your own, I'm happy to add it to the database, provided you give all the testing details, information like `lspci` and `dmesg` logs, etc. in a GitHub issue, and follow the project's conventions for card details. +* **Fix problems with the repository:** If you find any typos, incorrect links or images, or other issues in this repository, please submit a pull request to fix the problem or [open a new issue](https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/new/choose) to point the problem out for someone else to fix. +* **Mail me a card or board:** I accept cards and boards mailed to me, and can occasionally pay shipping as well. I credit senders in all videos/posts that result from donated card testing! + +## General instructions for contributing +To contribute to **Raspberry Pi PCIe Devices**, follow these steps: +1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repository. +2. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) that new repository to your device. +3. Create a [new branch](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/managing-branches#creating-a-branch). +3. (Optional) use `jekyll serve` to build the site in your local development environment while you're working on it. +4. Once you're satisfied with your changes, [commit them](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project). +5. [Push](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/pushing-changes-to-github) the changes to the correct branch. +6. Create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). +7. Give yourself a high five, you did a great job. Thanks for contributing! + +## Add a card +Add a new file named after the card in the appropriate `_cards_[type]` directory. +Copy the template out of [`card-template.md`](card-template.md) into this new file and follow the instructions it contains. + +### Specific example: Adding a network card +To add a network card to the database: +1. Make sure a GitHub [issue](https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues) exists for the card. Open a new issue for it you find that there isn't one. +2. Copy the template into a new Markdown file you create inside `_cards_network`. +3. Fill in the card information as described in [`card-template.md`](card-template.md). +4. Place a picture of the card named network-[name-of-card-here-minus-brackets].jpg inside the `images/` folder. +5. Submit a pull request with your changes. + +## Add a board +Add a new file named after the card in the appropriate `_boards_cm` directory. +Copy the template out of [`board-template.md`](board-template.md) into this new file and follow the instructions it contains. + +# Development + +Once you have Jekyll running and the [raspberry-pi-pcie-devices repository](https://github.com/geerlingguy/raspberry-pi-pcie-devices) cloned, you can build and run the site locally. + +### Build the site locally +1. In the command line, `cd` into the `raspberry-pi-pcie-devices` folder that contains the cloned repository. +2. To build the site, run `jekyll serve`. +3. You should now be able to access the local site at http://localhost:4000 in your web browser of choice. + +As long as `jekyll serve` is running, you'll be able to watch the site and all changes you make to it in real time. + +# Support +Drop a ⭐ if this project helped you! + +![Patreon](https://img.shields.io/badge/-Patreon-f96854?style=for-the-badge&logo=patreon&logoColor=white) + +# Authors +### Jeff Geerling +* Creator and maintainer +* [@geerlingguy](https://github.com/geerlingguy) on GitHub +* [![YouTube](https://img.shields.io/youtube/channel/subscribers/UCR-DXc1voovS8nhAvccRZhg?style=social)](https://www.youtube.com/c/JeffGeerling) + +### Katie Geerling +* Documentation writer and part-time contributor +* [@punnypenguins](https://github.com/punnypenguins) on GitHub + +# License + +This project is maintained by [Jeff Geerling](https://www.jeffgeerling.com/). The Raspberry Pi Compute Module 4 is a product of [Raspberry Pi (Trading) Limited](https://www.raspberrypi.org/about/). + +_**Raspberry Pi PCIe Devices** uses the [GNU General Public License, version 3](https://opensource.org/licenses/GPL-3.0)._ diff --git a/board-template.md b/board-template.md new file mode 100644 index 000000000..3a3d66ac4 --- /dev/null +++ b/board-template.md @@ -0,0 +1,44 @@ +--- +layout: board +title: "Name of Board Here" +short_description: Insert a single sentence summary of the board here. +status: Here +picture: "/images/board-(and-then-insert-name-here-without-parentheses).jpg" +github_issue: "https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/ID-here" +link: https://amzn.to/product-link-here +videos: [] +--- +# INSTRUCTIONS: + +### Create a new file in the `_boards_cm` directory. + +1. Title it with the board name in all-lowercase, using dashes to separate words. +2. Save it as Markdown file (.md extension). +3. Paste the contents of this template into the new file. +4. Replace all the values in its top section with the proper information: + - `layout`: Should be left alone! Don't change this. + - `title`: Replace *Name of Board Here* with the full name of the board. + - `short_description`: + - `status`: Can be one of these: + * prototype + * production + - `picture`: Can have a path to a picture like `/images/[card type]-card-name.jpg`, or `false`. + - `card type` can be + - adapter + - gpu + - m2 + - multimedia + - network + - other + - storage + - usb + - `file type` can be + - png + - jpg + - jpeg + Make sure you remember to drop the image into the `images` folder before you submit your pull request! + - `github_issue`: Should link to the GitHub issue corresponding to this card. + - `link`: should link to the Amazon product page for this card. If no Amazon listing is available, you can substitute a different website instead. + - `videos`: Is a list of YouTube video URLs. If there is a video to add, delete the `[]`, hit return, tab in once, add a dash, press the spacebar, and then paste the video url. + +Finally, replace all content below the second `---` line with a description of the board, save your changes, and submit the finished entry via pull request. diff --git a/card-template.md b/card-template.md index 2ac3809df..a1fc0e7cd 100644 --- a/card-template.md +++ b/card-template.md @@ -1,20 +1,49 @@ --- layout: card title: "Name of Card Here" -picture: "/images/name-of-image-here.jpg" -functionality: "Currently Testing" -driver_required: "Yes" +picture: "/images/[card type]-(and-then-insert-name-here-without-parentheses).jpg" +functionality: "Functionality goes here" +driver_required: "Answer goes here" github_issue: "https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/ID-here" buy_link: https://amzn.to/product-link-here videos: [] --- -Copy this template into the appropriate `_cards_[type]` directory, and replace all the values above with the proper information: +# INSTRUCTIONS: - - `picture`: can have a path to a picture like `/images/[type]-card.jpg`, or `false` - - `functionality`: can be one of "Currently Testing", "Full", "Partial", or "None" - - `driver_required`: can be one of "Yes", "Maybe", or "No" - - `github_issue`: should link to the GitHub issue corresponding to this card. - - `buy_link`: should link to the Amazon product page for this card. - - `videos`: is a list of YouTube video URLs. +### Create a new file in the appropriate `_cards_[type]` directory. -Then replace the text in this area with a description of the card. +1. Title it with the card name in all-lowercase, using dashes to separate words. +2. Save it as Markdown file (.md extension). +3. Paste the contents of this template into the new file. +4. Replace all the values in its top section with the proper information: + - `layout`: Should be left alone! Don't change this. + - `title`: Replace *Name of Card Here* with the full name of the board. + - `picture`: Can have a path to a picture like `/images/[card type]-card-name.jpg`, or `false`. + - `card type` can be + - adapter + - gpu + - m2 + - multimedia + - network + - other + - storage + - usb + - `file type` can be + - png + - jpg + - jpeg + Make sure you remember to drop the image into the `images` folder before you submit your pull request! + - `functionality`: Can be one of the following: + * "Currently Testing" + * "Full" + * "Partial" + * "None" + - `driver_required`: Can be one of the following: + * "Yes" + * "Maybe" + * "No" + - `github_issue`: Should link to the GitHub issue corresponding to this card. + - `buy_link`: Should link to the Amazon product page for this card. If no Amazon listing is available, you can substitute a different website instead. + - `videos`: Is a list of YouTube video URLs. If there is a video to add, delete the `[]`, hit return, tab in once, add a dash, press the spacebar, and then paste the video url. + +Finally, replace all content below the second `---` line with a description of the card, save your changes, and submit the finished entry via pull request.