Skip to content

Commit c610116

Browse files
committed
feat: Update readme and add contributing guide
Updates readme with key features and setup. Adds contributing guide for content and code contributions.
1 parent 192dfb0 commit c610116

File tree

2 files changed

+219
-319
lines changed

2 files changed

+219
-319
lines changed

CONTRIBUTING.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
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

Comments
 (0)