Skip to content

Commit 184b4fe

Browse files
ntindlentindle
committed
docs: add docs
1 parent 8ab7052 commit 184b4fe

File tree

2 files changed

+363
-0
lines changed

2 files changed

+363
-0
lines changed

‎docs/CONTIRBUTING.md

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Contributing to UNT Robotics Website
2+
3+
Thank you for considering contributing to the UNT Robotics website! This document provides guidelines and instructions for contributing to the project.
4+
5+
## Code of Conduct
6+
7+
All contributors are expected to adhere to our code of conduct:
8+
9+
1. Be respectful and inclusive of all contributors
10+
2. Follow UNT's academic integrity policies
11+
3. Maintain professionalism in communications
12+
4. Report any inappropriate behavior to project maintainers
13+
14+
## Getting Started
15+
16+
1. Fork the repository
17+
2. Clone your fork locally
18+
3. Set up your development environment (see GETTING_STARTED.md)
19+
4. Create a new branch for your feature/fix
20+
5. Make your changes
21+
6. Submit a pull request
22+
23+
## Development Workflow
24+
25+
### 1. Branching Strategy
26+
27+
- `main` - Production branch
28+
- `develop` - Development branch
29+
- Feature branches: `feature/your-feature-name`
30+
- Bugfix branches: `fix/bug-description`
31+
32+
### 2. Commit Messages
33+
34+
Follow conventional commits format:
35+
36+
```
37+
type(scope): description
38+
39+
[optional body]
40+
41+
[optional footer]
42+
```
43+
44+
Types:
45+
46+
- `feat`: New feature
47+
- `fix`: Bug fix
48+
- `docs`: Documentation changes
49+
- `style`: Code style changes
50+
- `refactor`: Code refactoring
51+
- `test`: Adding/modifying tests
52+
- `chore`: Maintenance tasks
53+
54+
Example:
55+
56+
```
57+
feat(merchandise): add size selection to t-shirt orders
58+
59+
- Added size dropdown component
60+
- Integrated with Printful API
61+
- Updated order processing logic
62+
63+
Closes #123
64+
```
65+
66+
### 3. Pull Request Process
67+
68+
1. Update documentation for any new features
69+
2. Add/update tests as needed
70+
3. Ensure all tests pass
71+
4. Update CHANGELOG.md
72+
5. Request review from maintainers
73+
6. Address review feedback
74+
75+
### 4. Code Style Guidelines
76+
77+
#### PHP
78+
79+
- Follow PSR-12 coding standards
80+
- Use type hints where possible
81+
- Document classes and methods with PHPDoc
82+
83+
```php
84+
/**
85+
* Process a new merchandise order
86+
*
87+
* @param int $orderId Order identifier
88+
* @param array $items List of ordered items
89+
* @return bool Success status
90+
*/
91+
public function processOrder(int $orderId, array $items): bool
92+
```
93+
94+
#### JavaScript
95+
96+
- Use ES6+ features
97+
- Follow Airbnb JavaScript Style Guide
98+
- Document functions with JSDoc
99+
100+
```javascript
101+
/**
102+
* Updates the shopping cart total
103+
* @param {Array} items - Cart items
104+
* @returns {number} Cart total
105+
*/
106+
function updateCartTotal(items) {
107+
```
108+
109+
#### HTML/CSS
110+
111+
- Use semantic HTML5 elements
112+
- Follow BEM naming convention for CSS
113+
- Maintain responsive design principles
114+
115+
### 5. Testing Guidelines
116+
117+
1. **Unit Tests**
118+
119+
- Write tests for new features
120+
- Update existing tests when modifying functionality
121+
- Aim for high coverage of critical paths
122+
123+
2. **Integration Tests**
124+
125+
- Test PayPal integration using sandbox
126+
- Test Discord bot functionality in test server
127+
- Verify email notifications
128+
129+
3. **Manual Testing**
130+
- Test on multiple browsers
131+
- Verify mobile responsiveness
132+
- Check accessibility compliance
133+
134+
### 6. Documentation
135+
136+
1. **Code Documentation**
137+
138+
- Document complex logic
139+
- Explain non-obvious decisions
140+
- Keep documentation up to date
141+
142+
2. **API Documentation**
143+
144+
- Document new endpoints
145+
- Include request/response examples
146+
- Note any authentication requirements
147+
148+
3. **User Documentation**
149+
- Update user guides for new features
150+
- Include screenshots where helpful
151+
- Document configuration changes
152+
153+
## Areas for Contribution
154+
155+
1. **High Priority**
156+
157+
- Payment processing improvements
158+
- Discord integration enhancements
159+
- Security updates
160+
- Performance optimization
161+
162+
2. **Feature Requests**
163+
164+
- Event management system
165+
- Member dashboard improvements
166+
- Automated testing
167+
- Analytics integration
168+
169+
3. **Documentation**
170+
- API documentation
171+
- Setup guides
172+
- User documentation
173+
- Code comments
174+
175+
## Getting Help
176+
177+
- Join our [Discord server](https://discord.gg/untrobotics)
178+
- Check our [Jira board](https://untrobotics.atlassian.net)
179+
- Check existing issues and discussions
180+
- Contact project maintainers
181+
- Review documentation
182+
183+
## Project Management
184+
185+
We use Jira to track our development work. You can find our project board at [untrobotics.atlassian.net](https://untrobotics.atlassian.net).
186+
187+
1. **Creating Issues**
188+
189+
- Check existing issues first
190+
- Use provided templates when available
191+
- Include clear reproduction steps for bugs
192+
- Tag appropriate components
193+
194+
2. **Working with Jira**
195+
- Assign yourself to issues you're working on
196+
- Update issue status as you progress
197+
- Link pull requests to issues
198+
- Add time tracking if applicable
199+
200+
## Security Issues
201+
202+
For security issues:
203+
204+
1. **DO NOT** create a public issue
205+
2. Email webmaster@untrobotics.com
206+
3. Include detailed description
207+
4. Wait for confirmation before disclosure
208+
209+
## License
210+
211+
By contributing, you agree that your contributions will be licensed under the project's license.
212+
213+
## Questions?
214+
215+
If you have questions about contributing:
216+
217+
1. Check existing documentation
218+
2. Search closed issues
219+
3. Ask in Discord
220+
4. Contact maintainers
221+
222+
Thank you for contributing to UNT Robotics!

‎docs/GETTING_STARTED.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Getting Started with UNT Robotics Web Platform
2+
3+
This guide will help you set up and run the UNT Robotics web platform locally for development.
4+
5+
## Prerequisites
6+
7+
- PHP 7.4 or higher
8+
- MySQL/MariaDB
9+
- Apache or Nginx web server
10+
- NodeJS
11+
12+
## Environment Setup
13+
14+
1. **Clone the Repository**
15+
16+
```bash
17+
git clone https://github.com/UNTRobotics/website.git
18+
cd website
19+
```
20+
21+
2. **Database Configuration**
22+
- Create a new MySQL database
23+
- Copy `config.sample.php` to `config.php`
24+
- Update database credentials in `config.php`:
25+
26+
```php
27+
define('DATABASE_HOST', 'localhost');
28+
define('DATABASE_USER', 'your_username');
29+
define('DATABASE_PASSWORD', 'your_password');
30+
define('DATABASE_NAME', 'untrobotics');
31+
```
32+
33+
3. **Import Database Schema**
34+
- Import all SQL files from the schema directory:
35+
36+
```bash
37+
mysql -u your_username -p your_database < schema/botathon_registration.sql
38+
mysql -u your_username -p your_database < schema/dues_payments.sql
39+
# ... (repeat for other .sql files)
40+
```
41+
42+
4. **Configure External Services**
43+
Update `config.php` with the following API credentials:
44+
- PayPal API credentials
45+
- Discord bot token
46+
- SendGrid API key
47+
- Printful API key
48+
```php
49+
define('PAYPAL_BUSINESS_ID', 'your_paypal_id');
50+
define('DISCORD_BOT_TOKEN', 'your_discord_token');
51+
define('SENDGRID_API_KEY', 'your_sendgrid_key');
52+
```
53+
54+
5. **Web Server Configuration**
55+
- For Apache, ensure mod_rewrite is enabled
56+
- Configure your virtual host to point to the project's public directory
57+
- Sample Apache configuration:
58+
59+
```apache
60+
<VirtualHost *:80>
61+
ServerName untrobotics.local
62+
DocumentRoot /path/to/website/public
63+
64+
<Directory /path/to/website/public>
65+
AllowOverride All
66+
Require all granted
67+
</Directory>
68+
</VirtualHost>
69+
```
70+
71+
6. **File Permissions**
72+
73+
```bash
74+
# Set proper permissions on storage directories
75+
chmod -R 775 storage/
76+
chown -R www-data:www-data storage/
77+
```
78+
79+
## Running the Application
80+
81+
1. **Start your web server and MySQL**
82+
83+
```bash
84+
sudo service apache2 start
85+
sudo service mysql start
86+
```
87+
88+
2. **Access the Application**
89+
- Visit http://localhost or your configured domain
90+
- The default admin credentials are:
91+
- Username: admin
92+
- Password: Change this on first login!
93+
94+
## Key Features
95+
96+
- **Membership Management**: Track member dues and registrations
97+
- **Event Management**: Handle event registrations like Botathon
98+
- **Payment Processing**: Integration with PayPal for merchandise and dues
99+
- **Discord Integration**: Automatic role management and notifications
100+
- **Merchandise Store**: Integration with Printful for merchandise fulfillment
101+
102+
## Troubleshooting
103+
104+
1. **Permission Issues**
105+
- Ensure storage directories are writable by web server
106+
- Check log files in `/var/log/apache2/` or equivalent
107+
108+
2. **Database Connection Issues**
109+
- Verify MySQL is running: `sudo service mysql status`
110+
- Check database credentials in config.php
111+
- Ensure database user has proper permissions
112+
113+
3. **Payment Integration Issues**
114+
- Verify PayPal API credentials
115+
- Check IPN (Instant Payment Notification) URL configuration
116+
- Review payment logs in `/logs` directory
117+
118+
## Development Guidelines
119+
120+
1. **Code Style**
121+
- Follow PSR-12 coding standards
122+
- Use meaningful variable and function names
123+
- Comment complex logic
124+
125+
2. **Testing**
126+
- Test payment flows using PayPal sandbox
127+
- Test Discord integrations in a test server
128+
- Verify email notifications using SendGrid sandbox
129+
130+
3. **Security**
131+
- Never commit sensitive credentials
132+
- Use prepared statements for database queries
133+
- Validate and sanitize all user input
134+
135+
## Additional Resources
136+
137+
- [UNT Robotics Website](https://untrobotics.com)
138+
- [Discord Server](https://discord.gg/untrobotics)
139+
- [PayPal Developer Documentation](https://developer.paypal.com/docs)
140+
- [Discord API Documentation](https://discord.com/developers/docs)
141+
- [Printful API Documentation](https://www.printful.com/docs)

0 commit comments

Comments
 (0)