mirror
/
photoview
mirror of https://github.com/photoview/photoview.git
1
Fork 0
Code
photoview/CONTRIBUTING.md

8.9 KiB
Raw Permalink Blame History

Contributing to Photoview

👋 Welcome to Photoview! Thank you for considering contributing to our project. Before you start, please take a moment to review this guide, which outlines the process for making contributions.

Contents

Getting Started

  1. Join project's Discord server: We have the Discord server with several channels, and you're welcome to join it to chat with the community and maintainers to ask for help, discuss some project-related topics, or help others.

  2. Browse Issues: Check the open issues, PRs, and discussions
    to see if your bug or idea has already been reported or discussed. If not, you can open a new issue. While browsing the issues, if you see an issue with useful from your PoV feature proposal or a bug, you're struggling with, it would be a helpful contribution to like the 1st post of that issue in the conversation tab (the issue description) - in this way, maintainers will know which issues should take priority. Of course, you can also add a comment with some useful info, which might be missing in the issue's thread - that would help as well.

  3. Check Open Source Guide: Familiarize yourself with the Open Source Guide for general information on contributing to open-source projects.

  4. Review Good First Issues: We've collected some good first issues that are suitable for newcomers. These are a great way to start contributing to Photoview.

Reporting Issues

If you encounter a bug, have a suggestion, or want to discuss an idea, please open a new issue or start a discussion. When opening an issue or starting a discussion, provide detailed information, including steps to reproduce the problem or a clear description of your idea.

Making Contributions

We welcome contributions in various forms, including bug fixes, feature enhancements, documentation improvements, and more. If you have the skills, it doesn't matter how small the contribution is welcome!

Here's how you can contribute

  • Code: If you're looking to help with code, check out the open issues. This filter contains issues, reviewed by maintainers, and waiting for contribution. In particular, they have the Photoview project assigned and don't have any invalid labels.
  • Code review: If you're a skilled developer with experience in the project's technology stack, we'd appreciate your help with code reviews of open PRs, providing well-described expert-level feedback with all info, needed for a contributor of any level of seniority to fix or optimize the PR.
  • Documentation: Spotted a typo, or think a document needs clarification? Go ahead and suggest changes in the documentation repo.
  • Ideas: Have an idea for a new feature? We'd love to hear it! Submit a new feature request issue.

Ticket workflows

< Bug >

The bug flow is the simplest of the two flows, and will most likely jump straight to development unless further discussion on architectural changes is required.

Development -> Code review -> Merge

< Feature >

New features are intended to be the longest flow as we want to ensure there is no time wasted by contributors. And that anyone can contribute to Photoview.

Discussion -> Dev Approach -> Development -> Code Review -> Merge

NOTE: Some features if basic may be able to skip stages.

Discussion

A new feature will start its life as an issue tagged as such, the initial author should highlight what they want from the feature. Then from this, interested community members can spark discussion and ideas about how this should work from a user flow perspective, for instance:

  • User navigates to settings
  • There is a specific section for x
  • There will be an Add button next to the title

Development approach

When sufficient conversation has happened, a label will be added to the ticket indicating it is ready to be picked up for a development approach, this gives someone the ability to investigate the existing architecture and design a high-level solution overview, doing so ensures that work is implemented into the system in a maintainable way, and also, hopefully, reduces the amount of rework when a code review happens. The development doesn't have to be done by the same person, and, hopefully, this will give less experienced members a chance to contribute to development.

Development

When the development approach has been written and signed off, it will be the time to develop the work. Again, this doesn't necessarily need to be done by the same person.

Code review

As with all PRs, the code will be reviewed by the community and maintainers before being merged ensuring the change meets the requirements, dev approach, and integrates correctly into the system. This will, hopefully, drive the community spirit and help people get support if they need it rather than giving up.

Steps to contribute to the code or documentation

  1. Fork the Repository: Fork the Photoview repository to your GitHub account.

  2. Clone the Repository: Clone your forked repository to your local machine.

  3. Create a Branch: Before making any changes, create a new branch to work on your contribution.

  4. Make Changes: Implement your changes, ensuring they align with the project's standards and guidelines.

  5. Test Your Changes: Before committing your changes, test them locally to verify their correctness and ensure they don't introduce any regressions.

  6. Commit Changes: Once you're satisfied with your changes, commit them with clear and descriptive commit messages.

  7. Push Changes to Your Fork: Push your changes to your forked repository on GitHub.

  8. Create a Pull Request: Create a pull request from your branch to the master branch of the Photoview repository. Provide a detailed description of your changes and reference any related issues.

  9. Review and Collaborate: Collaborate with project maintainers and address any feedback or review comments on your pull request.

Code Standards

When contributing code, please adhere to the following standards:

  • Follow the existing coding style and conventions used throughout the project.
  • Write clean, readable, and well-commented code.
  • Ensure your changes pass all existing tests and write additional tests for new functionality.
  • Ensure that existing Photoview users can migrate to the new version, containing your changes, as smoothly as possible: with no (or minimal) manual actions (which are well documented and clearly indicated to the user) and no data loss.
  • GitHub Actions, executed for your PR, shouldn't report issues, new to the master branch.
  • Ensure your changes are documented in the project documentation, Readme, and other applicable places in the case, they change the existing user experience.

Documentation

Improving documentation is a valuable contribution. If you find areas where documentation can be enhanced or if you have insights into better explaining existing features, feel free to update the relevant documentation files by creating a PR in the documentation repo.

Licensing

By contributing to Photoview, you agree that your contributions will be licensed under the terms of the GNU Affero General Public License (AGPL) version 3. Ensure that your contributions comply with this license.

How to get help

There are several ways to get help for your contribution to the project:

  • Search for the answer in the project's documentation, issues, PRs, and discussions.
  • We have the Discord server with several channels, and you're welcome to join it to chat with the community and maintainers.
  • Start a Discussion in the repo, providing a detailed and complete description of your case, environment, and the problem.