|
1 | | -# How to Contribute |
| 1 | +# Contributing to HireAI |
2 | 2 |
|
3 | | -We welcome contributions to this project! If you have an HR AI product you'd like to add, please follow these steps. |
| 3 | +Thank you for your interest in contributing to HireAI! This document provides guidelines and instructions for contributing. |
4 | 4 |
|
5 | | -## Adding a New Product Analysis |
| 5 | +## Table of Contents |
6 | 6 |
|
7 | | -1. **Fork the repository:** Start by forking the project to your own GitHub account. |
8 | | -2. **Create a new analysis file:** In the root directory, create a new markdown file for your analysis. The filename should be in the format `product-name-analysis.md`. |
9 | | -3. **Use the template:** Copy the content of `_templates/analysis_template.md` into your new file. This will give you the correct structure for the analysis. |
10 | | -4. **Fill out the analysis:** Complete the analysis to the best of your ability. Be objective and provide concrete examples where possible. |
11 | | -5. **Update the data file:** Open the `_data/products.yml` file and add an entry for your new product. Make sure to include the `name`, `url`, `analysis` (linking to your new file), `description`, and `tags`. |
12 | | -6. **Bake enrichment (recommended for `layout: analysis`):** Run `ruby _scripts/bake_analysis_enrichment.rb` to generate the Evaluation Guide, tag checklists, and related products block directly into Markdown. |
13 | | -7. **Create a pull request:** Once you're happy with your analysis, create a pull request to merge your changes into the main repository. |
| 7 | +- [Getting Started](#getting-started) |
| 8 | +- [Development Setup](#development-setup) |
| 9 | +- [Project Structure](#project-structure) |
| 10 | +- [Adding a New Product](#adding-a-new-product) |
| 11 | +- [Writing Analysis Articles](#writing-analysis-articles) |
| 12 | +- [Creating Tag Pages](#creating-tag-pages) |
| 13 | +- [Code Style Guidelines](#code-style-guidelines) |
| 14 | +- [Submitting Changes](#submitting-changes) |
14 | 15 |
|
15 | | -## Contribution Guidelines |
| 16 | +## Getting Started |
16 | 17 |
|
17 | | -* **Be objective:** Provide a fair and balanced analysis of the product. |
18 | | -* **Be thorough:** The more detailed your analysis, the more valuable it will be to others. |
19 | | -* **Cite your sources:** If you're quoting statistics or making specific claims, please include a link to the source. |
20 | | -* **Tags must have pages:** If you add a new tag, create the matching page under `tags/` (slug: lowercase, spaces → `-`). |
| 18 | +### Prerequisites |
| 19 | + |
| 20 | +- Ruby 2.7 or higher |
| 21 | +- Bundler gem |
| 22 | +- Git |
| 23 | + |
| 24 | +### Development Setup |
| 25 | + |
| 26 | +1. **Clone the repository** |
| 27 | + ```bash |
| 28 | + git clone https://github.com/Digidai/HireAI.git |
| 29 | + cd HireAI |
| 30 | + ``` |
| 31 | + |
| 32 | +2. **Install dependencies** |
| 33 | + ```bash |
| 34 | + bundle install |
| 35 | + ``` |
| 36 | + |
| 37 | +3. **Run the development server** |
| 38 | + ```bash |
| 39 | + bundle exec jekyll serve --livereload |
| 40 | + ``` |
| 41 | + |
| 42 | +4. **Open in browser** |
| 43 | + ``` |
| 44 | + http://localhost:4000 |
| 45 | + ``` |
| 46 | + |
| 47 | +## Project Structure |
| 48 | + |
| 49 | +``` |
| 50 | +HireAI/ |
| 51 | +├── _analyses/ # Product analysis articles (150+ files) |
| 52 | +├── _data/ |
| 53 | +│ ├── products.yml # Main product database |
| 54 | +│ └── tag_checklists.yml # Tag evaluation checklists |
| 55 | +├── _includes/ # Reusable HTML components |
| 56 | +├── _layouts/ # Page layout templates |
| 57 | +├── _sass/ # SCSS modules |
| 58 | +│ ├── _variables.scss # CSS custom properties |
| 59 | +│ ├── _base.scss # Reset and base styles |
| 60 | +│ ├── _sidebar.scss # Navigation sidebar |
| 61 | +│ ├── _components.scss # Cards, buttons, tags |
| 62 | +│ ├── _layouts.scss # Page layouts |
| 63 | +│ ├── _product-detail.scss |
| 64 | +│ ├── _markdown.scss # Markdown content |
| 65 | +│ └── _responsive.scss # Media queries |
| 66 | +├── _scripts/ # Build and validation scripts |
| 67 | +├── assets/ |
| 68 | +│ ├── css/main.scss # Main stylesheet entry |
| 69 | +│ ├── js/main.js # JavaScript functionality |
| 70 | +│ └── images/ # Static images |
| 71 | +├── tags/ # Tag pages (95+ files) |
| 72 | +└── *.md # Root-level pages |
| 73 | +``` |
| 74 | + |
| 75 | +## Adding a New Product |
| 76 | + |
| 77 | +### Step 1: Add to Product Database |
| 78 | + |
| 79 | +Edit `_data/products.yml` and add your product under the appropriate era category: |
| 80 | + |
| 81 | +```yaml |
| 82 | +- era: "2020s - Intelligence Platforms" |
| 83 | + icon: "🧠" |
| 84 | + products: |
| 85 | + - name: "Your Product Name" |
| 86 | + url: "https://product-website.com" |
| 87 | + description: "Brief description (max 100 chars)" |
| 88 | + tags: |
| 89 | + - "ATS" |
| 90 | + - "AI" |
| 91 | + analysis: "_analyses/your-product-analysis.md" |
| 92 | +``` |
| 93 | +
|
| 94 | +### Step 2: Create Analysis Article |
| 95 | +
|
| 96 | +Create a new file in `_analyses/`: |
| 97 | + |
| 98 | +```markdown |
| 99 | +--- |
| 100 | +layout: analysis |
| 101 | +title: "Your Product Name Analysis" |
| 102 | +description: "Deep-dive analysis of Your Product Name" |
| 103 | +permalink: /your-product-analysis/ |
| 104 | +--- |
| 105 | +
|
| 106 | +## Overview |
| 107 | +
|
| 108 | +Your analysis content here... |
| 109 | +``` |
| 110 | + |
| 111 | +### Step 3: Create Missing Tag Pages |
| 112 | + |
| 113 | +If you introduced new tags, create corresponding pages in `tags/`: |
| 114 | + |
| 115 | +```markdown |
| 116 | +--- |
| 117 | +layout: tag_page |
| 118 | +tag: "Your New Tag" |
| 119 | +title: "Your New Tag" |
| 120 | +description: "Products with Your New Tag capability" |
| 121 | +permalink: /tags/your-new-tag/ |
| 122 | +--- |
| 123 | +
|
| 124 | +Optional introductory content about this tag. |
| 125 | +``` |
| 126 | + |
| 127 | +### Step 4: Validate Your Changes |
| 128 | + |
| 129 | +Run the validation script: |
| 130 | + |
| 131 | +```bash |
| 132 | +ruby _scripts/check_site_data.rb |
| 133 | +``` |
| 134 | + |
| 135 | +Expected output: |
| 136 | +``` |
| 137 | +products=X |
| 138 | +analysis_pages=X |
| 139 | +tag_pages=X |
| 140 | +OK |
| 141 | +``` |
| 142 | + |
| 143 | +### Step 5: Bake Enrichment Content |
| 144 | + |
| 145 | +Run the enrichment script to add related products and checklists: |
| 146 | + |
| 147 | +```bash |
| 148 | +ruby _scripts/bake_analysis_enrichment.rb |
| 149 | +``` |
| 150 | + |
| 151 | +## Writing Analysis Articles |
| 152 | + |
| 153 | +### Required Front Matter |
| 154 | + |
| 155 | +```yaml |
| 156 | +--- |
| 157 | +layout: analysis |
| 158 | +title: "Product Name Analysis" |
| 159 | +description: "Concise description for SEO" |
| 160 | +permalink: /product-name-analysis/ |
| 161 | +product_name: "Product Name" |
| 162 | +website: "https://product.com" |
| 163 | +tags: |
| 164 | + - "Tag1" |
| 165 | + - "Tag2" |
| 166 | +--- |
| 167 | +``` |
| 168 | + |
| 169 | +### Recommended Structure |
| 170 | + |
| 171 | +1. **Overview** - What the product does |
| 172 | +2. **Key Features** - Main capabilities |
| 173 | +3. **Use Cases** - Ideal scenarios |
| 174 | +4. **Pros & Cons** - Balanced assessment |
| 175 | +5. **Pricing** - If publicly available |
| 176 | +6. **Alternatives** - Similar products |
| 177 | + |
| 178 | +### Writing Tips |
| 179 | + |
| 180 | +- Be objective and factual |
| 181 | +- Include specific feature names |
| 182 | +- Cite official sources when possible |
| 183 | +- Update `last_updated` when making changes |
| 184 | + |
| 185 | +## Creating Tag Pages |
| 186 | + |
| 187 | +### Tag Page Template |
| 188 | + |
| 189 | +```markdown |
| 190 | +--- |
| 191 | +layout: tag_page |
| 192 | +tag: "Tag Name" |
| 193 | +title: "Tag Name" |
| 194 | +description: "Description for SEO" |
| 195 | +permalink: /tags/tag-slug/ |
| 196 | +--- |
| 197 | +
|
| 198 | +Introduction paragraph about what this tag represents. |
| 199 | +``` |
| 200 | + |
| 201 | +### Adding Tag Checklists |
| 202 | + |
| 203 | +Edit `_data/tag_checklists.yml`: |
| 204 | + |
| 205 | +```yaml |
| 206 | +tag-slug: |
| 207 | + - "Checklist item 1" |
| 208 | + - "Checklist item 2" |
| 209 | + - "Checklist item 3" |
| 210 | +``` |
| 211 | + |
| 212 | +## Code Style Guidelines |
| 213 | + |
| 214 | +### SCSS |
| 215 | + |
| 216 | +- Use CSS custom properties (variables) from `_variables.scss` |
| 217 | +- Follow BEM-like naming: `.block`, `.block-element`, `.block--modifier` |
| 218 | +- Keep selectors shallow (max 3 levels) |
| 219 | +- Mobile-first media queries |
| 220 | + |
| 221 | +### JavaScript |
| 222 | + |
| 223 | +- Use ES6+ syntax |
| 224 | +- Implement debounce for search inputs |
| 225 | +- Check for element existence before attaching listeners |
| 226 | +- No jQuery dependency |
| 227 | + |
| 228 | +### Liquid Templates |
| 229 | + |
| 230 | +- Escape user-generated content: `{{ value | escape }}` |
| 231 | +- Use `{% if %}` guards for optional values |
| 232 | +- Prefer includes for repeated HTML |
| 233 | + |
| 234 | +## Submitting Changes |
| 235 | + |
| 236 | +### Before Submitting |
| 237 | + |
| 238 | +1. Run validation: `ruby _scripts/check_site_data.rb` |
| 239 | +2. Test locally: `bundle exec jekyll serve` |
| 240 | +3. Check mobile responsiveness |
| 241 | +4. Verify all links work |
| 242 | + |
| 243 | +### Pull Request Process |
| 244 | + |
| 245 | +1. Fork the repository |
| 246 | +2. Create a feature branch: `git checkout -b feature/your-feature` |
| 247 | +3. Make your changes |
| 248 | +4. Commit with clear messages |
| 249 | +5. Push to your fork |
| 250 | +6. Open a Pull Request |
| 251 | + |
| 252 | +### Commit Message Format |
| 253 | + |
| 254 | +``` |
| 255 | +type: brief description |
| 256 | + |
| 257 | +- Detail 1 |
| 258 | +- Detail 2 |
| 259 | +``` |
| 260 | +
|
| 261 | +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test` |
| 262 | +
|
| 263 | +### Review Criteria |
| 264 | +
|
| 265 | +- [ ] Passes validation scripts |
| 266 | +- [ ] Follows code style guidelines |
| 267 | +- [ ] Mobile-responsive |
| 268 | +- [ ] No broken links |
| 269 | +- [ ] Clear documentation for new features |
| 270 | +
|
| 271 | +## Questions? |
| 272 | +
|
| 273 | +- Open an [Issue](https://github.com/Digidai/HireAI/issues) |
| 274 | +- Check existing [Discussions](https://github.com/Digidai/HireAI/discussions) |
21 | 275 |
|
22 | 276 | Thank you for contributing! |
0 commit comments