Skip to content

Latest commit

 

History

History
153 lines (105 loc) · 12.6 KB

CONTRIBUTING.md

File metadata and controls

153 lines (105 loc) · 12.6 KB

CONTRIBUTING.md

Contributing to SCPkit

Thank you for your interest in contributing to SCPkit! We're excited to have you as part of our growing community. This document outlines the guidelines and best practices for contributing to this project.

Table of Contents

  1. CONTRIBUTING.md
    1. Contributing to SCPkit
      1. Table of Contents
      2. Code of Conduct
      3. Issues
      4. Pull Requests
      5. Coding Standards
      6. Testing
      7. Documentation
      8. Community

Code of Conduct

All contributors to this project are expected to follow our Code of Conduct. By participating in this project, you agree to abide by its terms.

Issues

Before submitting an issue, please:

  1. Check if the issue has already been reported by searching the existing issues.
  2. Follow the issue template provided and fill in all the required information.

When creating an issue, please use one of the templates for Bug reports or feature requests. For any fields that are not applicable, please use N/A or None.

Remember that the more detailed and specific your feature request is, the easier it will be for us to evaluate and potentially implement it.

Pull Requests

We follow a trunk-based development model for our codebase. This means that all changes should be made in short-lived feature branches and merged directly into the main branch through pull requests. Please follow these guidelines to ensure a smooth and efficient contribution process:

  1. Create a new branch from the latest main branch for each new feature or bug fix. Use a descriptive branch name that reflects the changes being made.
  2. Keep your changes focused and limited to a single feature or bug fix. If you find another issue while working on your branch, create a new issue and a separate branch for it.
  3. Commit your changes using the Conventional Commits standard. This helps maintain a clean and readable commit history. Your commit messages should follow this format: <type>(<scope>): <description>. For example: 
    fix(auth): resolve login failure due to incorrect token validation
  4. Sign your commits using GPG. This adds an extra layer of security and ensures the authenticity of your contributions. Follow the GitHub documentation on signing commits to set up and use GPG.
  5. Before submitting a pull request, ensure that your changes are up-to-date with the latest main branch. Rebase your branch if necessary.
  6. Open a pull request, and provide a clear and concise title and description that follows the Conventional Commits standard. Include any relevant issue numbers in the description by using keywords like "Closes #123" or "Fixes #123".
  7. Request a review from one or more project maintainers or collaborators. Be prepared to address any feedback, suggestions, or requested changes.
  8. Once your pull request is approved and all tests have passed, a project maintainer will squash and merge your changes into the main branch.

Please note that pull requests that do not follow the guidelines or are incomplete may experience a delay in order to gather additional information. We appreciate your understanding and cooperation in maintaining a high-quality codebase.

Coding Standards

Adhering to a consistent set of coding standards is crucial for maintaining a clean, readable, and maintainable codebase. By following these guidelines, you help ensure that SCPkit remains a high-quality project that is easy to understand, modify, and extend.

Here are some general guidelines for writing code that conforms to the project's coding standards:

  1. Write clean and readable code: Keep your code simple, clear, and concise. Use descriptive variable and function names, add comments to explain complex or non-obvious parts of the code, and break down large functions or classes into smaller, more manageable pieces.

  2. Optimize for performance and security: Write code that is efficient, secure, and avoids common pitfalls and vulnerabilities. Be mindful of performance bottlenecks, memory leaks, and security risks when designing and implementing your solutions.

  3. Document your code: Include comments and docstrings to explain the purpose, functionality, and usage of your code. This helps other contributors understand your code and makes it easier for them to maintain and extend it.

  4. Stay consistent with existing code: When making changes or additions to the codebase, try to match the style, structure, and conventions of the existing code. This ensures that the codebase remains coherent and easy to navigate.

  5. Adhere to the DRY (Don't Repeat Yourself) principle: Avoid duplicating code and logic across the codebase. Instead, refactor and reuse code whenever possible to minimize maintenance overhead and potential inconsistencies.

To contribute code that follows the project's coding standards:

  1. Create a new branch from the latest main branch.
  2. Make your changes or additions to the code, following the guidelines above.
  3. Commit your changes using the Conventional Commits standard, as described in the [Pull Requests](#pull-requests section.
  4. Sign your commits using GPG, as described in the Pull Requests section.
  5. Open a pull request with a clear and concise title and description, following the Conventional Commits standard.
  6. Request a review from one or more project maintainers or collaborators.

By adhering to the project's coding standards, you help create a strong foundation for the continued growth and success of SCPkit. Thank you for your commitment to maintaining a high-quality codebase!

Testing

Thorough and consistent testing is essential for maintaining the stability, reliability, and security of SCPkit. By contributing tests, you help ensure that the project remains robust and resistant to bugs, regressions, and vulnerabilities. Here are some guidelines for writing and contributing tests:

  1. Follow the testing framework and conventions: Familiarize yourself with the testing framework, tools, and conventions used in the project. Write tests that are consistent with the existing test suite and follow best practices.
  2. Write tests for new features and bug fixes: When adding a new feature or fixing a bug, make sure to include tests that cover the changes. This helps prevent regressions and ensures that the changes work as intended across different environments and configurations.
  3. Improve existing tests: If you find existing tests that are incomplete, unclear, or lacking in coverage, feel free to improve them. This may involve refactoring, adding new test cases, or improving test descriptions.
  4. Ensure tests are reliable and maintainable: Write tests that are easy to understand, maintain, and update. Avoid using hard-coded values, magic numbers, or brittle logic that may cause tests to fail unexpectedly or become difficult to maintain.
  5. Run tests locally: Before submitting a pull request, run the entire test suite locally to ensure that your changes do not introduce new test failures or break existing functionality.

To contribute tests, follow the same process as for code contributions:

  1. Create a new branch from the latest main branch.
  2. Add or modify tests as needed.
  3. Commit your changes using the Conventional Commits standard, with a test type in the commit message. For example: 
    test(auth): add test cases for login failure scenarios
  4. Sign your commits using GPG, as described in the Pull Requests section.
  5. Open a pull request with a clear and concise title and description, following the Conventional Commits standard.
  6. Request a review from one or more project maintainers or collaborators.

Your contributions to the project's test suite help ensure the long-term quality and stability of SCPkit. Thank you for your efforts in keeping the project robust and reliable!

Documentation

Well-written and up-to-date documentation is crucial for the success and usability of any project. Contributions to improve the documentation are highly appreciated and play a vital role in helping other users and developers understand, use, and extend SCPkit.

Here are some guidelines for contributing to the project's documentation:

  1. Stay consistent: Follow the existing documentation style, structure, and format. This ensures that the documentation remains coherent and easy to navigate.
  2. Use clear and concise language: Write in simple, easy-to-understand language. Avoid jargon, complex sentences, or unnecessary information. Keep in mind that the documentation should be accessible to users with various levels of expertise.
  3. Provide examples: Whenever possible, include examples, code snippets, or screenshots to illustrate your points. This helps users better understand the concepts and apply them in practice.
  4. Keep documentation up-to-date: Make sure to update the documentation whenever you make changes to the code, fix bugs, or introduce new features. Outdated documentation can cause confusion and hinder the adoption of the project.
  5. Proofread and review: Before submitting your changes, proofread your work to ensure it is free of grammatical errors, typos, or inconsistencies. Request reviews from other contributors or maintainers to ensure the quality and accuracy of the documentation.
  6. Organize and structure: Ensure that the documentation is well-organized and structured, with a logical flow of information. Use headings, subheadings, and lists to break up large blocks of text and make the content more readable.

To contribute to the documentation, follow the same process as for code contributions:

  1. Create a new branch from the latest main branch.
  2. Make your changes or additions to the documentation.
  3. Commit your changes using the Conventional Commits standard, with a docs type in the commit message. For example: 
    docs(api): add examples and improve clarity for authentication section
  4. Sign your commits using GPG, as described in the Pull Requests section.
  5. Open a pull request with a clear and concise title and description, following the Conventional Commits standard.
  6. Request a review from one or more project maintainers or collaborators.

By contributing to the documentation, you're helping to make SCPkit more accessible and user-friendly for everyone. Thank you for your valuable contributions!

Community

We are committed to fostering an open, inclusive, and welcoming community around SCPkit. By contributing to this project, you are joining a diverse group of developers, users, and enthusiasts who share a common passion for improving and advancing cybersecurity.

Here are some ways to get involved and stay connected with the community:

  1. Join the discussion: Participate in the project's discussions on GitHub, forums, mailing lists, or chat rooms. Ask questions, share your ideas, or help others with their issues.
  2. Attend community events: Look for meetups, conferences, webinars, or other events related to SCPkit and cybersecurity. These gatherings provide opportunities for learning, networking, and collaboration.
  3. Spread the word: Share your experiences and knowledge about SCPkit with your network, colleagues, or friends. Write blog posts, create tutorials or present talks about the project and its benefits.
  4. Provide feedback: Your feedback is invaluable to the continued development and improvement of the project. Share your thoughts on new features, report bugs, or suggest enhancements through GitHub issues or other communication channels.
  5. Support other contributors: Encourage and support fellow contributors by reviewing their pull requests, answering their questions, or providing mentorship.
  6. Stay up-to-date: Follow the project's news, announcements, and releases on social media, newsletters, or the project's website. This will help you stay informed about the latest developments and opportunities for collaboration.

Remember that everyone in the community is expected to follow the Code of Conduct and contribute respectfully and constructively. Let's work together to make SCPkit a thriving and successful project that benefits everyone involved.