🛡️ Contributing to CyberShield

Thank you for your interest in contributing to CyberShield! We welcome contributions from the community and appreciate your efforts to help make this project better.

📋 Table of Contents

Code of Conduct
Getting Started
Development Setup
How to Contribute
Coding Standards
Commit Message Guidelines
Pull Request Process
Testing
Reporting Bugs
Suggesting Features

🤝 Code of Conduct

Please read and follow our Code of Conduct in all interactions with the community.

🚀 Getting Started

Prerequisites

Git installed on your system
A GitHub account
Basic knowledge of HTML, CSS, and JavaScript
Node.js (v14 or higher) for running the local server

Fork & Clone

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/Cybershield_URL.git
cd Cybershield_URL

Add upstream remote:

git remote add upstream https://github.com/ORIGINAL_OWNER/Cybershield_URL.git

⚙️ Development Setup

1. Install Dependencies

npm install

2. Configure API Key

Get your Google Safe Browsing API key from Google Cloud Console

Create a .env file in the root directory:

SAFE_BROWSING_API_KEY=your_api_key_here

Never commit .env file — it's in .gitignore for security

3. Run Local Server

npm start
# or
node server.js

Server runs on http://localhost:3000

4. Open in Browser

Navigate to http://localhost:3000 in your browser.

🎯 How to Contribute

Types of Contributions

We welcome:

Bug Fixes — Identify and fix issues
Features — Add new functionality (discuss in issues first)
Documentation — Improve README, guides, code comments
Accessibility — Improve ARIA labels, keyboard navigation
Performance — Optimize code and assets
UI/UX — Improve design and user experience
Tests — Add test coverage

Contribution Workflow

Check existing issues — Avoid duplicate work
Create an issue — Describe your proposal
Wait for approval — Get feedback before coding
Create a dedicated branch — Use clear, lowercase, hyphen-separated names prefixed by category:
- feat/feature-name (new features)
- fix/bug-name (bug fixes)
- docs/doc-update (documentation changes)
- style/style-change (CSS or layout updates)
- refactor/refactoring-task (code structure refactoring)
- test/test-scenario (adding or expanding tests)
Make your changes — Follow coding standards
Commit — Write clear commit messages matching Conventional Commits rules
Push — Push to your fork
Create PR — Submit pull request with description
Respond to reviews — Address feedback
Merge — Your PR will be merged once approved

📝 Coding Standards

HTML

Use semantic HTML5 tags (<header>, <main>, <footer>, etc.)
Always include alt attributes for images
Use aria-label and aria-describedby for accessibility
Keep markup clean and well-structured
Use proper heading hierarchy (h1 > h2 > h3)

CSS

Use CSS custom properties for colors and spacing
Follow BEM naming convention for classes: .block__element--modifier
Mobile-first responsive design
Use meaningful class names
Avoid inline styles
Keep specificity low
Group related rules together

JavaScript

Use vanilla JavaScript (no jQuery)
Use const by default, let for variables that change
Avoid var declarations
Use meaningful variable and function names
Keep functions small and focused
Add comments only for complex logic
Use arrow functions for callbacks
Handle errors gracefully

Example Code Style

// Good: clear, concise, follows standards
async function checkSecurity() {
  const input = document.getElementById('urlInput').value.trim();
  
  if (!input) {
    showError('Enter a URL');
    return;
  }

  const url = formatUrl(input);
  const result = await fetchSecurityData(url);
  displayResult(result);
}

📝 Commit Message Guidelines

Format

<type>: <subject>

<body>

<footer>

Type

feat: — New feature
fix: — Bug fix
docs: — Documentation changes
style: — Code style changes (formatting, missing semicolons, etc.)
refactor: — Code refactoring without changing functionality
perf: — Performance improvements
test: — Adding or updating tests
chore: — Build process, dependencies, etc.

Subject

Use imperative mood ("add" not "added")
Don't capitalize first letter
No period at the end
Max 50 characters
Be specific and descriptive

Body (Optional)

Explain what and why, not how
Wrap at 72 characters
Separate from subject with blank line

Footer (Optional)

Reference issues: Closes #123
Break changes: BREAKING CHANGE: description

Examples

feat: add url validation with specific error messages

Improve user experience by providing clear feedback when
URL format is invalid. Handles international domains and
special characters properly.

Closes #45

fix: resolve mobile navbar overflow on small screens

docs: update installation instructions

🔄 Pull Request Process

Before Creating PR

Update your branch with latest main:

git fetch upstream
git rebase upstream/main

Test your changes thoroughly
Check code standards — Run linting if available
Review your own changes first

PR Description Template

## Related Issue
Closes #issue_number

## Summary
Brief explanation of changes.

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
How you tested these changes.

## Screenshots (if applicable)
Add images for UI changes.

## Checklist
- [x] Code follows project style
- [x] Tested locally
- [x] No unrelated changes included
- [x] Documentation updated (if needed)

PR Guidelines

Title — Short, descriptive, lowercase
Link to issue — Always reference the related issue
Small PRs — Easier to review, faster to merge
One feature per PR — Don't combine unrelated changes
Review comments — Respond promptly to feedback
Keep conversations professional — Be respectful

What Gets Accepted

✅ Good PRs:

Fix a specific bug
Add one focused feature
Improve accessibility
Enhance documentation
Optimize performance
Fix UI/UX issues

❌ Avoid:

Giant multi-feature PRs
Unrelated changes bundled together
Low-quality or spam contributions
Breaking changes without discussion

🧪 Testing

Manual Testing

Test all changes in browser
Test on different screen sizes (mobile, tablet, desktop)
Test with keyboard navigation
Test with screen readers
Check all example URLs work

Testing Checklist

🐛 Reporting Bugs

Before Reporting

Check if bug already exists in Issues
Test in latest version
Test in different browsers

Bug Report Template

Title: Clear, specific issue title

Description:

## Problem
What is the bug? Describe what you expected vs what happened.

## Steps to Reproduce
1. Step 1
2. Step 2
3. Step 3

## Current Behavior
What actually happens?

## Expected Behavior
What should happen?

## Environment
- Browser: 
- OS: 
- Device: 

## Screenshots
Add screenshots if applicable.

## Additional Context
Any other relevant information.

💡 Suggesting Features

Feature Request Template

Title: Clear, specific feature request