Skip to content
Naomi's Documentation

Contributing Documentation

1. Scope and General Contribution Guidelines

1.1 Overview

This document outlines the general guidelines for contributing to our projects. It serves as a high-level framework for all contributors, whether you’re submitting code, documentation, or other forms of contribution.

1.2 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.3 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 or Codeberg account.
  • For SSH signing, use a key linked to your GitHub or Codeberg 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.4 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.5 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 license. By submitting a contribution, you are agreeing to license your work under the terms of this license.

1.6 Intellectual Property

By contributing to our projects, you affirm that:

  • You own the copyright to your contribution or have authorization 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.

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

1.8 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 centralized 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

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 Forking the Repository

  1. Navigate to the original repository on Codeberg.
  2. Click the “Fork” button in the upper right corner of the page.
  3. Select your account as the destination for the fork.
  4. Wait for Codeberg to create a copy of the repository in your account.

3.2 Cloning Your Fork

  1. Go to your forked repository on Codeberg.

  2. Click the “Code” button and copy the URL (HTTPS or SSH, depending on your setup).

  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 GitHub credentials if prompted.

3.3 Setting Up the Upstream Remote

Adding the original repository as an upstream remote allows you to easily keep your fork up-to-date.

  1. Change into the project directory:

    cd <project-name>

  2. Add the upstream remote:

    git remote add upstream <original-repository-url>

    Replace <original-repository-url> with the git URL of the original repository.

  3. Verify the new remote:

    git remote -v

    You should see entries for both origin (your fork) and upstream.

3.4 Keeping Your Fork Up-to-Date

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

  1. Fetch the branches and commits from the upstream repository:

    git fetch upstream

  2. Check out your fork’s local main branch:

    git checkout main

  3. Merge changes from upstream/main into your local main branch:

    git merge upstream/main

3.5 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 server: https://chat.nhcarrigan.com

4. Claiming an Issue

4.1 Finding an Issue

  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 your fork 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 fork.
  5. Open a pull request when ready for review (see Pull Request Guidelines in section [X]).

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 Fork

Before starting work, ensure your forked version is up to date with the original repository. If you’ve set up the upstream remote as mentioned in Section 3, follow these steps:

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

  2. Run the following commands:

    Terminal window
    git fetch upstream
    git merge upstream/main

5.2 Creating a New Branch

Always create a new branch for your work:

  1. Create and switch to a new branch:

    Terminal window
    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 fork periodically:

    Terminal window
    git push origin <branchname>

5.4 Committing Changes

When you’re ready to commit your changes:

  1. Stage your changes:

    Terminal window
    git add .

    Or stage specific files:

    Terminal window
    git add <file1> <file2>

  2. Commit:

    Terminal window
    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
    • Additonal 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 any existing tests to ensure your changes haven’t broken anything:

    Terminal window
    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 chat server. Our community is here to support you!

6. Submitting a Pull Request

6.1 Pushing Your Changes

  1. Push your changes to your forked repository:
Terminal window
git push -u origin <branchname>
  • -u sets the upstream, linking your local branch to the remote branch
  • origin specifies your forked repository as the destination
  • <branchname> is the name of your local branch
  1. Ensure the push is successful and your changes appear in your forked repository on Codeberg.

6.2 Creating the Pull Request

  1. Navigate to your forked repository on Codeberg.
  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 your fork 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. 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 fork:

    Terminal window
    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 your fork 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.

Thank you for providing that section. I’ll expand and improve it to make it more comprehensive and encourage a wider range of contributions. Here’s an enhanced version:

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

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 behavior 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
  • Organizing or participating in community events or meetups
  • Promoting the project on social media or relevant forums
  • Helping to moderate community discussions

8.8 Internationalization and Localization

Make the project accessible to a global audience:

  • Translate user interfaces
  • Provide localized 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
  • Organize 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 organize 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.