|
| 1 | +# Contributing to Open Neuromorphic |
| 2 | + |
| 3 | +First off, thank you for considering contributing to the Open Neuromorphic (ONM) website! We're thrilled you're here and appreciate you taking the time to help us grow. This is a community-driven project, and every contribution, no matter how small, is valuable. |
| 4 | + |
| 5 | +This document provides guidelines for contributing to the ONM website. Please read it carefully to ensure a smooth and effective collaboration process. |
| 6 | + |
| 7 | +Before you start, please read our [Code of Conduct](./CODE_OF_CONDUCT.md). We expect all contributors to adhere to it in all interactions with the project. |
| 8 | + |
| 9 | +## Table of Contents |
| 10 | +- [Ways to Contribute](#ways-to-contribute) |
| 11 | +- [Getting Started: Local Development Setup](#getting-started-local-development-setup) |
| 12 | +- [How to Submit Changes](#how-to-submit-changes) |
| 13 | + - [Reporting Bugs and Suggesting Enhancements](#reporting-bugs-and-suggesting-enhancements) |
| 14 | + - [Your First Code Contribution](#your-first-code-contribution) |
| 15 | + - [Submitting a Pull Request](#submitting-a-pull-request) |
| 16 | +- [Content Contribution Guide](#content-contribution-guide) |
| 17 | + - [General Guidelines](#general-guidelines) |
| 18 | + - [Adding Blog Posts](#adding-blog-posts) |
| 19 | + - [Adding Events (Workshops, Student Talks, etc.)](#adding-events-workshops-student-talks-etc) |
| 20 | + - [Adding Hardware or Software Pages](#adding-hardware-or-software-pages) |
| 21 | + - [Adding Contributor Profiles](#adding-contributor-profiles) |
| 22 | +- [Image Guidelines](#image-guidelines) |
| 23 | +- [Style and Coding Guidelines](#style-and-coding-guidelines) |
| 24 | + - [Commit Messages](#commit-messages) |
| 25 | + |
| 26 | +## Ways to Contribute |
| 27 | + |
| 28 | +There are many ways to contribute to the ONM website: |
| 29 | + |
| 30 | +* **Reporting Bugs:** If you find a bug on the site, please report it in our [GitHub Issues](https://github.com/open-neuromorphic/open-neuromorphic.github.io/issues). |
| 31 | +* **Suggesting Enhancements:** Have an idea for a new feature or an improvement? Open an issue to start a discussion. |
| 32 | +* **Adding Content:** Contribute a blog post, add a new neuromorphic hardware or software entry, or update an existing page. |
| 33 | +* **Improving Code:** Help us improve the website's templates, styles, or functionality. |
| 34 | + |
| 35 | +For a more user-friendly overview of how to get involved with the community, please visit our [Getting Involved page](https://open-neuromorphic.org/getting-involved/). |
| 36 | + |
| 37 | +## Getting Started: Local Development Setup |
| 38 | + |
| 39 | +To work on the website locally, you'll need to set up a development environment. |
| 40 | + |
| 41 | +### Prerequisites |
| 42 | + |
| 43 | +* **Hugo (Extended version):** `0.147.7` or later. |
| 44 | +* **Node.js:** `22.16.0` or later (which includes `npm`). |
| 45 | +* **Go:** `1.24.3` or later. |
| 46 | + |
| 47 | +### Setup Steps |
| 48 | + |
| 49 | +1. **Fork and Clone the Repository:** |
| 50 | + First, fork the repository to your own GitHub account, then clone it to your local machine. |
| 51 | + |
| 52 | + ```bash |
| 53 | + git clone https://github.com/YOUR_USERNAME/open-neuromorphic.github.io.git |
| 54 | + cd open-neuromorphic.github.io |
| 55 | + ``` |
| 56 | + |
| 57 | +2. **Install Dependencies:** |
| 58 | + This project uses `npm` to manage development tools like Tailwind CSS. |
| 59 | + |
| 60 | + ```bash |
| 61 | + npm install |
| 62 | + ``` |
| 63 | + |
| 64 | +3. **Run the Development Server:** |
| 65 | + This command starts Hugo's local server, which will watch for changes and automatically refresh your browser. |
| 66 | +
|
| 67 | + ```bash |
| 68 | + npm run dev |
| 69 | + ``` |
| 70 | +
|
| 71 | + The site will be available at `http://localhost:1313/`. |
| 72 | +
|
| 73 | +## How to Submit Changes |
| 74 | +
|
| 75 | +### Reporting Bugs and Suggesting Enhancements |
| 76 | +
|
| 77 | +Use [GitHub Issues](https://github.com/open-neuromorphic/open-neuromorphic.github.io/issues) to report bugs or suggest new features. Please provide as much detail as possible, including steps to reproduce for bugs. |
| 78 | +
|
| 79 | +### Submitting a Pull Request |
| 80 | +
|
| 81 | +All code and content changes should be submitted via a Pull Request (PR). |
| 82 | +
|
| 83 | +1. **Create a Branch:** Create a new branch from `main` for your changes. Use a descriptive name like `feature/new-hardware-page` or `fix/mobile-menu-bug`. |
| 84 | + ```bash |
| 85 | + git checkout -b feature/your-feature-name |
| 86 | + ``` |
| 87 | +
|
| 88 | +2. **Make Your Changes:** Edit or add files as needed. |
| 89 | +
|
| 90 | +3. **Commit Your Changes:** Write clear, concise commit messages. See our [Commit Message Guidelines](#commit-messages). |
| 91 | + ```bash |
| 92 | + git commit -m "feat(hardware): Add page for Intel Loihi 2" |
| 93 | + ``` |
| 94 | +
|
| 95 | +4. **Push to Your Fork:** |
| 96 | + ```bash |
| 97 | + git push origin feature/your-feature-name |
| 98 | + ``` |
| 99 | +
|
| 100 | +5. **Open a Pull Request:** Go to the original repository on GitHub and open a Pull Request from your forked branch to the `main` branch. Provide a clear title and description for your PR. If it resolves an existing issue, link it using `Closes #issue-number`. |
| 101 | +
|
| 102 | +## Content Contribution Guide |
| 103 | +
|
| 104 | +Adding new content is one of the best ways to contribute. We use Hugo's [archetypes](https://gohugo.io/content-management/archetypes/) to ensure new content has the correct structure. |
| 105 | + |
| 106 | +### General Guidelines |
| 107 | + |
| 108 | +* **Use Archetypes:** Always create new content with `hugo new <path>`. This pre-fills the necessary front matter. For content that should have its own images and assets, create a page bundle by adding `index.md` to the path. |
| 109 | + * Example: `hugo new blog/my-new-post/index.md` |
| 110 | +* **Draft Status:** New content is created with `draft: true`. This prevents it from being published. When your content is ready, change this to `draft: false`. |
| 111 | +* **SEO is Key:** |
| 112 | + * **`title`:** 50-60 characters. Make it descriptive and keyword-rich. |
| 113 | + * **`description`:** 120-160 characters. This is the summary shown in search engine results. |
| 114 | + |
| 115 | +### Adding Blog Posts |
| 116 | + |
| 117 | +1. **Create the file:** |
| 118 | + ```bash |
| 119 | + hugo new blog/your-post-title-slug/index.md |
| 120 | + ``` |
| 121 | +2. **Location:** `content/blog/your-post-title-slug/index.md` |
| 122 | +3. **Images:** Place images for the post inside the `content/blog/your-post-title-slug/` directory. |
| 123 | +4. **Front Matter:** Fill in the `title`, `description`, `author`, and `image` (for the banner). |
| 124 | + |
| 125 | +### Adding Events (Workshops, Student Talks, etc.) |
| 126 | + |
| 127 | +1. **Create the file:** |
| 128 | + * **Workshop:** `hugo new workshops/your-event-slug/index.md` |
| 129 | + * **Student Talk:** `hugo new neuromorphic-computing/student-talks/your-talk-slug/index.md` |
| 130 | + * **Hacking Hour:** `hugo new neuromorphic-computing/software/hacking-hours/your-session-slug/index.md` |
| 131 | +2. **Front Matter:** Fill in all event-specific fields: `title`, `author`, `date` (event date), `start_time`, `end_time`, `time_zone`, `upcoming`, `video` (add YouTube ID after the event), `image`, `speaker_photo`, and `speaker_bio`. Ensure the `type` field is set correctly (`workshops`, `student-talks`, or `hacking-hours`). |
| 132 | + |
| 133 | +### Adding Hardware or Software Pages |
| 134 | + |
| 135 | +1. **Create the file:** |
| 136 | + * **Hardware:** `hugo new neuromorphic-computing/hardware/manufacturer-chip-name/index.md` |
| 137 | + * **Software:** `hugo new neuromorphic-computing/software/snn-frameworks/software-name/index.md` |
| 138 | +2. **Front Matter:** Follow the structure in the respective archetype. These pages have detailed front matter for specifications. |
| 139 | +3. **Images:** Place logos and product images inside the new directory. |
| 140 | + |
| 141 | +### Adding Contributor Profiles |
| 142 | + |
| 143 | +To link content to an author, a contributor profile is required. |
| 144 | + |
| 145 | +1. **Create the file:** |
| 146 | + ```bash |
| 147 | + hugo new contributors/full-name-slug/index.md |
| 148 | + ``` |
| 149 | + The slug should be the person's name, lowercase and hyphenated (e.g., `jens-e-pedersen`). |
| 150 | +2. **Front Matter:** |
| 151 | + * The **`title`** field **must be the person's full name**. This exact string is used to link them from the `author` field in other content. |
| 152 | + * Add a profile `image` (square) and `social` links. |
| 153 | + |
| 154 | +## Image Guidelines |
| 155 | + |
| 156 | +* **Placement:** For content-specific images (banners, figures, speaker photos), place them inside the page bundle directory (e.g., `content/blog/my-post/`). |
| 157 | +* **Global Images:** For general site images, use the `static/images/` directory. |
| 158 | +* **Dimensions:** |
| 159 | + * **Banners / Open Graph (OG) Images:** 1200x630px. |
| 160 | + * **Profile / Speaker Photos:** Square (e.g., 200x200px). |
| 161 | +* **OG Images:** The site automatically generates Open Graph images for social sharing based on the page's `title` and `description`. Providing a high-quality `image` in the front matter (1200x630px) will override the generated one for that page. |
| 162 | + |
| 163 | +## Style and Coding Guidelines |
| 164 | + |
| 165 | +* **Templates:** Hugo templates are located in `layouts/`. |
| 166 | +* **Styling:** We use Tailwind CSS. Custom styles are in `assets/scss/`. Add project-specific overrides to `assets/scss/custom.scss`. |
| 167 | +* **JavaScript:** Custom scripts are in `assets/js/main.js`. |
| 168 | + |
| 169 | +### Commit Messages |
| 170 | + |
| 171 | +Please follow a conventional commit format to keep the history clean and understandable. |
| 172 | + |
| 173 | +* `feat`: A new feature (e.g., `feat(search): Add live search functionality`). |
| 174 | +* `fix`: A bug fix (e.g., `fix(css): Correct mobile menu alignment`). |
| 175 | +* `docs`: Documentation-only changes (e.g., `docs: Update contribution guide`). |
| 176 | +* `style`: Code style changes (e.g., `style: Format SCSS files`). |
| 177 | +* `refactor`: Code changes that neither fix a bug nor add a feature. |
| 178 | +* `content`: For adding or updating content (e.g., `content(blog): Add post on hardware trends`). |
| 179 | +* `chore`: Build process or tooling changes (e.g., `chore: Upgrade Tailwind CSS to v3.4`). |
| 180 | + |
| 181 | +--- |
| 182 | + |
| 183 | +Thank you again for your interest in contributing. We look forward to your pull requests! |
0 commit comments