Skip to content

Commit df0bf37

Browse files
AllanKoderAllanKoder
authored
Icon Changes, and README updates (#65)
* Icons * changed again * github readme and contributing
1 parent 23c4649 commit df0bf37

12 files changed

Lines changed: 2183 additions & 1914 deletions

‎CONTRIBUTING.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Contributing to ComputerScienceResources.com
2+
3+
First off, **thank you** for considering contributing to ComputerScienceResources.com!
4+
5+
This project is built on the values of **helpfulness**, **kindness**, and **collaboration**. Whether you're fixing a typo, reporting a bug, or implementing a major feature, your contribution matters and is appreciated.
6+
7+
## Table of Contents
8+
9+
- [Code of Conduct](#code-of-conduct)
10+
- [How Can I Contribute?](#how-can-i-contribute)
11+
- [Reporting Bugs](#reporting-bugs)
12+
- [Suggesting Features](#suggesting-features)
13+
- [Your First Code Contribution](#your-first-code-contribution)
14+
- [Pull Requests](#pull-requests)
15+
- [Development Setup](#development-setup)
16+
- [Style Guide](#style-guide)
17+
- [Community](#community)
18+
19+
## Code of Conduct
20+
21+
This project is a safe and welcoming space for everyone. We expect all contributors to:
22+
23+
- Be respectful and considerate
24+
- Welcome newcomers and help them get started
25+
- Give and receive constructive feedback gracefully
26+
- Focus on what's best for the community
27+
- Show empathy towards other community members
28+
29+
Unacceptable behavior includes harassment, trolling, insulting comments, or any conduct that would make others feel unwelcome.
30+
31+
## How Can I Contribute?
32+
33+
### Reporting Bugs
34+
35+
Found a bug? Help us squash it!
36+
37+
1. **Check existing issues** to see if it's already been reported
38+
2. **Open a new issue** if it hasn't been reported yet
39+
3. **Include details:**
40+
- What you expected to happen
41+
- What actually happened
42+
- Steps to reproduce the issue
43+
- Your environment (OS, browser, PHP version, etc.)
44+
- Screenshots if applicable
45+
46+
### Suggesting Features
47+
48+
Have an idea? We'd love to hear it!
49+
50+
1. **Check the [Discussions tab](https://github.com/AllanKoder/ComputerScienceResources.com/discussions)** to see if someone else has suggested it
51+
2. **Start a new discussion** with your feature idea
52+
3. **Explain:**
53+
- What problem does this solve?
54+
- How would it work?
55+
- Why would this be valuable to users?
56+
57+
Once there's community interest, we can create an issue and start working on it!
58+
59+
### Your First Code Contribution
60+
61+
New to the project? Welcome! Here's how to get started:
62+
63+
1. **Look for `good first issue` labels** — these are beginner-friendly tasks
64+
2. **Read through the [Development Setup](#development-setup)** section below
65+
3. **Comment on the issue** to let others know you're working on it
66+
4. **Ask questions!** We're here to help. No question is too small.
67+
68+
### Pull Requests
69+
70+
Ready to submit your changes? Here's the process:
71+
72+
1. **Fork the repository** and create a new branch from `master`
73+
```bash
74+
git checkout -b feature/your-feature-name
75+
# or
76+
git checkout -b fix/your-bug-fix
77+
```
78+
79+
2. **Make your changes** following our [Style Guide](#style-guide)
80+
81+
3. **Test your changes** thoroughly
82+
```bash
83+
./sail test
84+
```
85+
86+
4. **Commit your changes** with clear, descriptive messages
87+
```bash
88+
git commit -m "Add feature: user profile avatars"
89+
```
90+
91+
5. **Push to your fork**
92+
```bash
93+
git push origin feature/your-feature-name
94+
```
95+
96+
6. **Open a Pull Request** with:
97+
- A clear title and description
98+
- Reference to any related issues (e.g., "Fixes #123")
99+
- Screenshots or GIFs if the changes are visual
100+
- Notes on any breaking changes
101+
102+
7. **Respond to feedback** — we might suggest changes or ask questions
103+
104+
## Development Setup
105+
106+
This project uses [Laravel 11](https://laravel.com/) (PHP 8.4+) as the backend framework, with [Inertia.js](https://inertiajs.com/) and [Vue 3](https://vuejs.org/) for the frontend. We use [Laravel Sail](https://laravel.com/docs/11.x/sail) for easy Docker-based development.
107+
108+
### Prerequisites
109+
110+
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) - Required for Laravel Sail
111+
- [Git](https://git-scm.com/)
112+
- Basic knowledge of PHP, Laravel, and Vue.js
113+
114+
We use [Laravel Sail](https://laravel.com/docs/11.x/sail) for easy setup and configuration. For detailed instructions, see the [Laravel Sail documentation](https://laravel.com/docs/11.x/installation#docker-installation-using-sail).
115+
116+
### Installation
117+
118+
1. **Clone your fork:**
119+
```bash
120+
git clone https://github.com/YOUR-USERNAME/ComputerScienceResources.com.git
121+
cd ComputerScienceResources.com
122+
```
123+
124+
2. **Install PHP dependencies:**
125+
```bash
126+
composer install
127+
```
128+
129+
3. **Set up environment:**
130+
```bash
131+
cp .env.example .env
132+
# Edit .env if needed
133+
```
134+
135+
4. **Generate application key:**
136+
```bash
137+
./sail artisan key:generate
138+
```
139+
140+
5. **Install JavaScript dependencies:**
141+
```bash
142+
./sail npm install
143+
```
144+
145+
6. **Run migrations:**
146+
```bash
147+
./sail artisan migrate
148+
```
149+
150+
7. **Start development servers:**
151+
```bash
152+
# Terminal 1: Start Laravel
153+
./sail up
154+
155+
# Terminal 2: Start Vite dev server
156+
./sail npm run dev
157+
```
158+
159+
8. **Visit the app** at `http://localhost`
160+
161+
### Running Tests
162+
163+
Always run tests before submitting a PR:
164+
165+
```bash
166+
# Run all tests
167+
./sail test
168+
169+
# Run specific test file
170+
./sail test tests/Feature/YourTest.php
171+
172+
# Exclude slow tests for faster feedback
173+
./sail test --exclude-group=slow
174+
```
175+
176+
## Style Guide
177+
178+
Following consistent code style makes collaboration easier! We follow the [Laravel naming conventions](https://webdevetc.com/blog/laravel-naming-conventions/) for controllers, models, migrations, and more.
179+
180+
### General Conventions
181+
182+
- **PascalCase** for class names: `ResourceController`, `CommentPolicy`, `ResourceReviewProcessed`
183+
- **camelCase** for methods and variables: `getUserProfile()`, `$resourceData`
184+
- **snake_case** for database columns, table names, migration files, and fields in request bodies: `created_at`, `resource_reviews`
185+
- **kebab-case** for Vue component props: `user-profile`, `comment-text`
186+
187+
### PHP & Laravel
188+
189+
- Follow [PSR-12](https://www.php-fig.org/psr/psr-12/) code standards (enforced by Pint)
190+
- Use [Laravel naming conventions](https://webdevetc.com/blog/laravel-naming-conventions/)
191+
- Keep controllers thin and focused on HTTP concerns
192+
- Place business logic in **Service classes** or **Actions**, not controllers
193+
- Use type hints and return types
194+
- Write descriptive variable and method names
195+
196+
**Run Pint to auto-fix code style:**
197+
```bash
198+
./sail pint
199+
```
200+
201+
### Vue & Frontend
202+
203+
- Use [Vue 3](https://vuejs.org/) with [Inertia.js](https://inertiajs.com/)
204+
- Use Vue 3 Composition API when possible
205+
- Follow [Vue style guide](https://vuejs.org/style-guide/)
206+
- Use [Tailwind CSS](https://tailwindcss.com/) for styling
207+
- Use `primary` and `secondary` color classes over raw hex values according to tailwind.config.js
208+
- Example: `class="bg-primary"`
209+
- Use existing components from `resources/js/Components/` whenever possible (e.g., `PrimaryButton.vue`, `SecondaryButton.vue`)
210+
211+
### Commit Messages
212+
213+
Write clear commit messages that explain **what** and **why**:
214+
215+
```bash
216+
# Good
217+
git commit -m "Add pagination to resource comments"
218+
git commit -m "Fix N+1 query in review listing"
219+
220+
# Not ideal
221+
git commit -m "Update stuff"
222+
git commit -m "WIP"
223+
```
224+
225+
## Debugging with Xdebug & VS Code
226+
227+
Xdebug is pre-configured in the Sail Docker environment for local debugging.
228+
229+
### Setup
230+
231+
1. **Ensure Xdebug is enabled:**
232+
- By default, Xdebug is enabled in Sail via the `SAIL_XDEBUG_MODE` and `SAIL_XDEBUG_CONFIG` environment variables in your `.env` file.
233+
234+
2. **VS Code Setup:**
235+
- Install the [PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug)
236+
- Add a launch configuration to your `.vscode/launch.json`:
237+
238+
```json
239+
{
240+
"version": "0.2.0",
241+
"configurations": [
242+
{
243+
"name": "Listen for Xdebug",
244+
"type": "php",
245+
"request": "launch",
246+
"port": 9003,
247+
"pathMappings": {
248+
"/var/www/html": "${workspaceFolder}"
249+
}
250+
}
251+
]
252+
}
253+
```
254+
255+
3. **Start debugging:**
256+
- Set breakpoints in your PHP code
257+
- Start the "Listen for Xdebug" configuration in VS Code
258+
- Trigger a request (web, test, or CLI) and Xdebug will connect to VS Code
259+
260+
## Deployment
261+
262+
For maintainers: We use Ansible for deployment with a `deploy.yaml` script and the inventory `production.ini`:
263+
264+
```bash
265+
ansible-playbook -i ./ansible/inventory/production.ini deploy.yml
266+
```
267+
268+
## Community
269+
270+
- **Questions?** Open a [Discussion](https://github.com/AllanKoder/ComputerScienceResources.com/discussions)
271+
- **Found a bug?** Open an [Issue](https://github.com/AllanKoder/ComputerScienceResources.com/issues)
272+
- **Want to chat?** Comment on existing issues or PRs
273+
274+
Remember: we're all learning together. Be patient, be kind, and have fun building something awesome!
275+
276+
---
277+
278+
**Thank you for contributing to ComputerScienceResources.com!** Your efforts help make learning computer science more accessible for everyone.

0 commit comments

Comments
 (0)