Skip to content

Latest commit

 

History

History
120 lines (76 loc) · 5.31 KB

CONTRIBUTING.md

File metadata and controls

120 lines (76 loc) · 5.31 KB

Contributing to WebShield

Thank you for your interest in contributing to WebShield! We welcome all contributions—whether it's reporting bugs, suggesting new features, improving documentation, or submitting code. By contributing to WebShield, you are helping improve a tool that promotes privacy and enhances the browsing experience for Safari users.

Code of Conduct

Please note that this project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report any unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

  • Xcode 15.0 or later
  • Swift 6.0 or later
  • macOS 14.0 or later for development

Setting up the development environment

  1. Fork the repository on GitHub.
  2. Clone your fork locally.
  3. Install project dependencies.
  4. Open Xcode and start coding!

How to Contribute

Issue policy

Please file any bugs you find, keeping the following in mind:

  • One issue per bug. Putting multiple things in the same issue makes both discussion and completion unnecessarily complicated.
  • Follow the detailed issue-reporting guidelines.
  • No build issues (or other support requests).
  • Don't comment on issues just to add a joke or irrelevant commentary. Many people get notified about comments so let's keep them relevant.

Code submission policy

TODO

  • Follow the Swift API Design Guidelines.
  • Use swift-format to ensure code style consistency.
  • Write self-documenting code and add comments where necessary.
  • Keep functions small and focused on a single task.
  • Code Style: Follow Swift's standard coding conventions. Keep code modular and avoid large, monolithic functions.
  • Commit Messages: Use clear, descriptive commit messages.
  • Testing: All code contributions should be covered by tests. Ensure tests pass before submitting. Please use Swift Testing.

See CodingStyle.md for more info.

Documentation Contributions

Improving documentation is a great way to contribute! If you find any outdated or unclear sections in the README or other documentation feel free to submit a PR.

Human language policy

The following applies to all user-facing strings, code, comments, and commit messages:

  • The official project language is American English with ISO 8601 dates and metric units.
  • Use proper spelling, grammar, and punctuation.
  • Write in an authoritative and technical tone.
  • Avoid contractions, slang, and idioms.
  • Avoid humor, sarcasm, and other forms of non-literal language.
  • Use gender-neutral pronouns, except when referring to a specific person.

Note that this also applies to debug logging and other internal strings, as they may be exposed to users in the future.

Testing policy

When possible, please include tests when fixing bugs or adding new features. Please use Swift Testing.

Review Process

Once you submit a pull request, a maintainer will review your changes. You can expect feedback within a few days. Here's what we look for:

  • Code quality: Is the code clean, readable, and maintainable?
  • Functionality: Does it perform the intended task? Does it introduce any regressions?
  • Tests: Are there sufficient tests for the new code?

Once approved, your changes will be merged into the main branch!

Branch Naming Conventions

  • Use feature/ for new features.
  • Use bugfix/ for bug fixes.
  • Use docs/ for documentation changes.
  • Use refactor/ for code refactoring.

Recognition

All contributors will be recognized in our CONTRIBUTORS file. We appreciate your hard work and dedication!

On neutrality

Our goal is to build an ad-blocker for everyone, irrespective of their specific opinions and worldviews. To achieve this, we strive to set our differences aside and focus on the shared goal of building the project.

This means:

  • We welcome contributions from anyone who is committed to the project's goals and respects the collaborative environment.
  • Our discussions and work will remain strictly related to project development. We do not take positions on issues outside this scope.
  • The project will not be used as a platform to advertise or promote causes unrelated to ad blocker development.
  • To maintain a focused and productive environment, discussions on societal politics and other divisive topics are discouraged in project spaces.
  • We encourage everyone to share their personal views and opinions outside project spaces. However, please keep project spaces focused on project goals.

Additional Resources

  • Documentation: Please refer to the WebShield documentation.
  • GitHub Issues: View or submit issues here.
  • Discussions: Join the community for discussions here.

Questions?

If you have any questions or need further clarification, please don't hesitate to reach out to the maintainers:

Thank you for your interest in improving WebShield. We look forward to your contributions!

License

By contributing to WebShield, you agree that your contributions will be licensed under the MIT License.