Contributing Documentation

ESTABLISHING CONTRIBUTION GUIDELINES AND REQUIREMENTS FOR ALL PROJECTS

1. INTRODUCTION AND LEGAL FRAMEWORK

1.1. Policy Overview

This Contributing Documentation (hereinafter referred to as “the Guidelines”) establishes mandatory guidelines, procedures, and requirements for all contributions to projects maintained by our organisation. These Guidelines operate within our comprehensive legal and policy framework, incorporating our Terms of Service, Privacy Policy, Community Code of Conduct, Contributor Covenant, and all applicable legal protections by reference.

1.2. Scope and Applicability

These Guidelines apply to all forms of contribution, including but not limited to code, documentation, artwork, design, and other materials submitted to any project maintained by our organisation. All contributors, regardless of status or experience level, are required to comply with these Guidelines.

IMPORTANT: Failure to comply with these Guidelines may result in rejection of contributions, requests for modification, or other appropriate actions as determined by project maintainers.

1.3. Project-Specific Instructions

While these guidelines apply broadly, individual projects may have unique requirements or processes. Always refer to the specific project’s documentation for:

• Supplemental instructions
• Project-specific workflows
• Coding standards
• Testing requirements
• Other relevant information

In case of any discrepancy between this document and project-specific guidelines, the project-specific instructions take precedence.

1.4. Commit Signing Requirements

All commits must be cryptographically signed using either GPG or SSH. This requirement serves to verify the authenticity and integrity of your contributions.

• For GPG signing, ensure your GPG key is associated with your GitHub account.
• For SSH signing, use a key linked to your GitHub account.

By signing your commit, you are certifying that:

• The commit adheres to our Contributor Covenant
• You have the right to submit the contribution under our project license.
• You understand and agree to our contribution terms.

1.5. Contributor Covenant

All contributors are expected to adhere to our Contributor Covenant. The full text of the Contributor Covenant can be found in its own document.

1.6. Licensing of Contributions

All contributions to our projects, including but not limited to code, documentation, artwork, and other materials, will be licensed under our global software licence. By submitting a contribution, you are agreeing to license your work under the terms of this license.

• Our global software licence: Naomi’s Public Licence
• Full text of the license: License Page

1.7. Intellectual Property

By contributing to our projects, you affirm that:

• You own the copyright to your contribution or have authorisation from the copyright owner to submit it under our license.
• Your contribution does not infringe on any third-party intellectual property rights.
• You grant us a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, and distribute your contribution.

1.8. Legal Compliance

Ensure all contributions comply with relevant laws and regulations, including export controls and data protection laws.

1.9. Acceptance of Contributions

While we appreciate all contributions, we reserve the right to reject any contribution that doesn’t meet our standards or align with our project goals. The project maintainers have final say on the inclusion of any contribution.

2. SECRETS MANAGEMENT

2.1. Overview

Proper management of secrets is crucial for maintaining the security and integrity of our projects. We use 1Password as our centralised secrets management solution. This section outlines our policies and procedures for handling secrets.

2.2. General Policy

• Plain-text secrets should never be stored on personal machines, development environments, or our servers.
• All secrets should be stored and managed through 1Password.

2.3. 1Password Setup and Usage

To work with secrets locally, you must set up the 1Password CLI (Command Line Interface) and integrate it with your 1Password desktop application.

2.3.1. Setup Instructions

• Install the 1Password desktop application if you haven’t already.
• Install the 1Password CLI. Instructions can be found at: https://developer.1password.com/docs/cli/get-started/
• Authenticate the CLI with your 1Password account.
• Configure your development environment to use the 1Password CLI for secret retrieval. https://developer.1password.com/docs/cli/secrets-environment-variables/

2.3.2. Best Practices

• Use environment variables to store secrets retrieved from 1Password during runtime.
• Never log or display secrets in any form.
• Rotate secrets regularly.

2.4. Handling Secrets in Code

• Development environment variables should be set in dev.env - changes to this file should generally be excluded from your contributions.
• Use 1Password references instead of actual secret values in configuration files.

3. SETTING UP YOUR DEVELOPMENT ENVIRONMENT

3.1. Gaining a Contributor Account

Contributor accounts are provided only to members of our team. Our technical positions are paid positions, and they are advertised separately when they are open.

Once accepted, you will be granted credentials as part of your onboarding.

3.2. Cloning A Project

1. Go to the repository on GitHub (https://github.com/spellware).

2. Click the “Code” button and copy the HTTPS URL.

3. Open your terminal or command prompt.

4. Navigate to the directory where you want to store the project.

5. Run the following command, replacing <url> with the URL you copied:

   git clone <url>

6. Enter your Git credentials if prompted.

3.3. Keeping Your Clone Up-to-Date

Regularly update your clone to incorporate changes from the upstream repository:

1. Check out the main branch:

   git checkout main

2. Pull changes from upstream to your local clone:

   git pull

3.4. Troubleshooting

If you encounter any issues during setup:

1. Check the project’s FAQ or troubleshooting guide (if available).
2. Search for similar issues in the project’s issue tracker.
3. If the problem persists, open a new issue with detailed information about the problem and steps to reproduce it.

You can also reach out to us in our Discord community: https://chat.spellware.dev

4. CLAIMING AN ISSUE

4.1. Finding an Issue

For All Contributors:

1. Navigate to the project’s issue tracker.
2. Browse open issues or use filters to find tasks that interest you.
3. Read the issue description thoroughly to understand the requirements and context.

4.2. Expressing Interest

1. If you find an issue you’d like to work on, comment on the issue expressing your interest.
2. Example comment: “I’m interested in working on this issue. May I be assigned to it?”
3. Wait for a project maintainer to respond and potentially assign the issue to you.

4.3. Issue Assignment

• Project maintainers will assign issues based on the order of interest and the contributor’s experience level.
• Once assigned, you’ll see your username in the “Assignees” section of the issue.

4.4. Already Assigned Issues

If an issue is already assigned:

1. Check the assignee and the last activity date.
2. If you’re still interested in contributing, you can: a. Comment on the issue expressing your interest to collaborate. b. Reach out to the assigned person to offer assistance or discuss collaboration.

We encourage collaboration and pair programming on complex issues!

4.5. Working on the Issue

1. Once assigned, create a new branch in the project for this specific issue.
2. Use a descriptive branch name, e.g., fix/issue-123-button-alignment.
3. Make your changes, committing regularly with clear, concise commit messages.
4. Push your changes to your branch.
5. Open a pull request when ready for review (see Pull Request Guidelines in section 6).

4.6. Keeping the Community Updated

1. Provide regular updates on your progress in the issue comments.
2. If you encounter obstacles, don’t hesitate to ask for help in the issue thread.
3. If you need to step away from an issue, please let us know so it can be reassigned if necessary.

4.7. Time Management

• Try to start working on the issue within a few days of assignment.
• If you haven’t made progress within a week, the issue may be unassigned to keep the project moving forward.
• If you need more time, communicate this in the issue comments.

4.8. Multiple Issues

• We encourage focusing on one issue at a time to ensure quality and timely completion.
• If you want to work on multiple issues, please complete one before requesting assignment to another.

4.9. Issue Labels

Pay attention to issue labels for additional context:

• good first issue: Suitable for newcomers to the project or open source.
• help wanted: Issues where we’re actively seeking community help.
• staff only: Issue that will require staff attention.

4.10. Respectful Communication

• Always be courteous and professional in issue discussions.
• Respect the decisions of project maintainers regarding issue assignments and priorities.
• If you disagree with something, express your thoughts constructively and be open to feedback.

5. WORKING ON YOUR ISSUE

5.1. Updating Your Clone

Before starting work, ensure your clone is up to date with the original repository.

1. Open your terminal and navigate to your project’s root directory.

2. Run the following commands:

   git checkout main
   git pull

5.2. Creating a New Branch

Always create a new branch for your work:

1. Create and switch to a new branch:

   git checkout -b <branchname>

2. Follow the branch naming convention: type/description

   • type: Indicates the nature of the changes (e.g., feat, fix, docs, refactor)
   • description: A brief, hyphenated description of the changes

   Examples:

   • feat/add-login-page
   • fix/resolve-memory-leak
   • docs/update-api-endpoints

5.3. Making Changes

1. Make your code changes, following the project’s coding standards and guidelines.

2. Regularly commit your changes with clear, concise messages.

3. Push your changes to your branch periodically:

   git push origin <branchname>

5.4. Committing Changes

When you’re ready to commit your changes:

1. Stage your changes:

   git add .

   Or stage specific files:

   git add <file1> <file2>

2. Commit:

   git commit

5.5. Commit Message Guidelines

• Follow Conventional Commit standards: type(scope): description such as docs: update contributing guidelines.
• Use the present tense (“Add feature” not “Added feature”)
• Use the imperative mood (“Move cursor to…” not “Moves cursor to…“)
• Limit the first line to 50 characters or less
  • Additional information can be included in the body
• Do NOT reference issues/PRs in your commit

Example:

feat: add user authentication system

Implement JWT-based authentication for API endpoints.

5.7. Testing Your Changes

• Run the linter to ensure your code complies with our style guidelines.

  pnpm lint # or the appropriate lint command for your project

• Run any existing tests to ensure your changes haven’t broken anything:

  pnpm test # or the appropriate test command for your project

• Add new tests for your changes if applicable.

5.8. Documentation

• Update relevant documentation to reflect your changes.
• If you’ve added new features, include appropriate documentation.

5.9. Preparing for Pull Request

Before submitting a pull request:

1. Check that your code adheres to the project’s style guidelines - the linters should pass.
2. Ensure the build succeeds.
3. Ensure all tests pass.
4. Review your changes and commit history.

If you’re unsure about any part of the process or need help, don’t hesitate to ask in our Discord community. Our community is here to support you!

6. SUBMITTING A PULL REQUEST

6.1. Pushing Your Changes

1. Push your changes to the repository:

git push -u origin <branchname>

• -u sets the upstream, linking your local branch to the remote branch
• origin specifies the project repository as the destination
• <branchname> is the name of your local branch

2. Ensure the push is successful and your changes appear in the repository on GitHub.

6.2. Creating the Pull Request

1. Navigate to the repository on GitHub.
2. You should see a prompt to create a pull request for your recently pushed branch. If not, click on the “Pull requests” tab and then the “New pull request” button.
3. Ensure the base repository is the original project repository and the base branch is main.
4. Select the project as the head repository and your recently pushed branch as the compare branch.

6.3. Filling Out the Pull Request

1. Change the title of your pull request to be a conventional commit message summarising all changes in that PR
2. Fill out the pull request description with as much information as possible. This typically includes:
   • A clear description of the changes
   • The issue number(s) your pull request addresses
   • Any additional context or explanations
3. Fill out the rest of the pull request form completely.
4. If your changes include visual elements, consider adding screenshots or GIFs to illustrate the modifications.

6.4. Pull Request Best Practices

• Ensure your PR addresses only one issue or adds one feature. If you have made multiple unrelated changes, consider breaking them into separate pull requests.
• Double-check that all tests pass and there are no conflicts with the base branch.
• If your PR is a work in progress, mark it as a draft pull request.

6.5. After Submitting

• Keep an eye on your pull request for any comments, requests for changes, or approval.
• Be prepared to make additional commits to your branch if changes are requested.

6.6. Updating Your Pull Request

If you need to make changes to your pull request:

1. Make the required changes in your local branch.

2. Commit the changes.

3. Push the new commits to your branch:

   git push origin <branchname>

4. The pull request will automatically update with your new commits.

6.7. Pull Request Etiquette

• Be patient. Maintainers are often managing multiple priorities.
• Be open to feedback and willing to make changes.
• Respond promptly to any questions or requests from reviewers.
• If there’s a delay in your ability to respond or make requested changes, leave a comment explaining the situation.

6.8. Merging and Closing

• Once your pull request is approved, a maintainer will merge it into the main project.
• After merging, you can delete your branch from the repository if you won’t be using it anymore.
• Celebrate your contribution to the project!

7. PULL REQUEST REVIEWS

7.1. Review Process Overview

• All pull requests require at least one approved review before merging.
• Reviews are primarily conducted by Naomi, but some projects may have additional reviewers.
• The review process helps maintain code quality, consistency, and project standards.

7.2. What Reviewers Look For

Reviewers typically assess the following aspects:

1. Code quality and style adherence
2. Functionality and correctness of the implementation
3. Test coverage and passing status
4. Documentation updates (if applicable)
5. Adherence to project-specific guidelines
6. Potential impact on existing features or performance

7.3. Types of Review Outcomes

1. Approved: Your pull request is ready to be merged.
2. Changes Requested: Modifications or additional information is needed before approval.
3. Commented: The reviewer has provided feedback but hasn’t explicitly approved or requested changes.

7.4. Responding to Review Feedback

If changes are requested:

1. Read all comments carefully to understand the requested modifications.
2. Ask for clarification if any feedback is unclear.
3. Make the necessary changes in your local branch.
4. Commit and push the changes to update your pull request.
5. Respond to each comment, explaining how you addressed the feedback or why you chose a different approach.

7.5. Best Practices for Handling Reviews

• Respond promptly to review comments (ideally within a few days).
• Be open to constructive criticism and willing to make changes.
• If you disagree with a suggestion, explain your reasoning politely and be open to discussion.
• Use the review process as a learning opportunity to improve your coding skills.

7.6. Timelines and Expectations

• We strive to review pull requests as quickly as possible, typically within a week.
• If your pull request requires changes, please address them promptly.
• Pull requests with outstanding change requests and no activity for a week may be closed as stale.
• If you need more time to address changes, communicate this in the pull request comments to prevent your contribution from being closed.

7.7. Multiple Iterations

• Complex changes may require multiple rounds of reviews and revisions.
• Stay engaged throughout the process and be patient if additional iterations are needed.

7.8. Learning from the Review Process

• Take note of common feedback to improve future contributions.
• Consider reviewing other pull requests to gain insights into the project’s standards and practices.

7.9. After Approval

Once your pull request is approved:

1. It will be merged into the main branch by a project maintainer.
2. Depending on the project’s deployment pipeline, your changes may be deployed immediately or as part of the next release cycle.

8. OTHER CONTRIBUTIONS

We value all types of contributions, not just code. There are many ways to contribute to our project, regardless of your technical experience or comfort level with the codebase. Here are several ways you can make a meaningful impact:

8.1. Documentation Updates

Clear and accurate documentation is crucial for any project. You can help by:

• Fixing typos, grammatical errors, or unclear phrasing
• Adding examples or clarifying existing explanations
• Creating new documentation for undocumented features
• Improving README files, API documentation, or user guides

8.2. Feature Requests

Your ideas can help shape the future of the project. To suggest a new feature:

1. Check existing issues to ensure your idea hasn’t been proposed
2. Clearly describe the feature and its potential benefits
3. If possible, outline how the feature might be implemented

Before you start:

Consider discussing your idea in our community chat before creating an issue to gather initial feedback.

8.3. Bug Reports

Identifying and reporting bugs is a valuable contribution. When reporting a bug:

1. Search existing issues to avoid duplicates
2. Provide a clear, concise description of the problem
3. Include steps to reproduce the bug
4. Describe the expected behaviour and what actually happened
5. If possible, include screenshots, error messages, or code samples

8.4. User Support

Helping other users is a great way to contribute to the community:

• Answer questions in our Discord server or other community platforms
• Share your knowledge and experiences with the project
• Guide new users through common issues or setup processes
• Create tutorials or blog posts about using the project

8.5. Design Contributions

If you have design skills, you can contribute by:

• Creating or improving project logos or icons
• Designing user interface mockups for new features
• Improving the overall user experience and accessibility
• Creating infographics or visual aids for documentation

8.6. Testing and Quality Assurance

Help improve the project’s stability by:

• Testing new features or bug fixes
• Performing usability testing and providing feedback
• Writing or improving automated tests
• Identifying edge cases or potential security issues

8.7. Community Building

Foster a welcoming and inclusive community by:

• Welcoming new contributors and helping them get started
• Organising or participating in community events or meetups
• Promoting the project on social media or relevant forums
• Helping to moderate community discussions

8.8. Internationalisation and Localisation

Make the project accessible to a global audience:

• Translate user interfaces
• Provide localised documentation
• Ensure the project supports multiple languages and cultures

8.9. Code Reviews

Even if you’re not comfortable making code changes, you can:

• Review pull requests for documentation or small changes
• Provide feedback on proposed features or bug fixes
• Help ensure code style and convention consistency

8.10. Fundraising and Sponsorship

If you have connections or experience in this area:

• Help identify potential sponsors or grants
• Assist with writing grant applications
• Organise fundraising events or campaigns

Or even make a donation yourself!

8.11. Mentoring

Share your knowledge and experience:

• Mentor new contributors
• Create learning resources for the project
• Participate in or organise coding workshops related to the project

Remember, all contributions, big or small, are valuable to the project. Don’t hesitate to get involved in any way you feel comfortable. If you have any questions about how to contribute or need help getting started, please reach out to us in our Discord server or through the project’s communication channels.

9. LIMITATION OF LIABILITY AND DISCLAIMERS

9.1. Reference to Comprehensive Liability Framework

IMPORTANT: Comprehensive liability limitations, damage exclusions, and maximum liability caps are set forth in our Limitation of Liability and Indemnification Policy, which is incorporated herein by reference.

9.2. Contribution Guidelines Disclaimer

These Guidelines establish mandatory requirements for contributions. However, compliance with these Guidelines does not guarantee acceptance of contributions. Project maintainers reserve the right to:

• Reject contributions that comply with these Guidelines for other valid reasons
• Request modifications beyond the scope of these Guidelines
• Modify or update these Guidelines at any time without prior notice
• Interpret Guideline requirements in specific contexts as necessary

9.3. Technical Accuracy Disclaimer

While we strive to maintain accurate and current information in these Guidelines, technical standards, tooling, and best practices evolve continuously. Contributors are responsible for:

• Verifying current tool versions and compatibility
• Ensuring their development environment matches project requirements
• Adapting to updates in these Guidelines as they are published
• Consulting project-specific documentation for additional requirements

10. CONCLUSION

These Contributing Guidelines represent our commitment to maintaining high-quality, consistent, and legally compliant contributions across all projects. By adhering to these standards, contributors help ensure that our projects remain accessible, professional, and aligned with our organisational values and legal obligations.

All contributors are expected to familiarise themselves with and comply with the requirements set forth in these Guidelines. Questions about specific requirements or requests for clarification should be directed to project maintainers through appropriate communication channels.

---

For questions about contribution requirements or to suggest improvements, please contact project maintainers through the designated channels outlined in our Contributor Covenant.