Create CONTRIBUTING.md (#943)
* Create CONTRIBUTING.md Creating a resource file for any developer who wants to contribute to this open-source project. Adding more details than what was already provided, giving a detailed walkthrough for newcomers on how to make changes in the code. * Implement the suggestions from the feedback, as well as merge the template from the discussion #934 --------- Co-authored-by: Konstantin Koval <kkb@ukr.net>
This commit is contained in:
Blake Schafer
GitHub
parent
365328457e
commit
dad4533983
|
|
@ -0,0 +1,172 @@
|
|||
# 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](#getting-started)
|
||||
- [Reporting Issues](#reporting-issues)
|
||||
- [Making Contributions](#making-contributions)
|
||||
- [Here's how you can contribute](#heres-how-you-can-contribute)
|
||||
- [Ticket workflows](#ticket-workflows)
|
||||
- [Bug](#-bug-)
|
||||
- [Feature](#-feature-)
|
||||
- [Steps to contribute to the code or documentation](#steps-to-contribute-to-the-code-or-documentation)
|
||||
- [Code Standards](#code-standards)
|
||||
- [Documentation](#documentation)
|
||||
- [Licensing](#licensing)
|
||||
- [How to get help](#how-to-get-help)
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Join project's Discord server**: We have the [Discord server](https://discord.gg/jQ392948u9)
|
||||
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](https://github.com/photoview/photoview/issues),
|
||||
[PRs](https://github.com/photoview/photoview/pulls), and [discussions](https://github.com/photoview/photoview/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](https://opensource.guide/)
|
||||
for general information on contributing to open-source projects.
|
||||
|
||||
4. **Review Good First Issues**: We've collected some [good first issues](https://github.com/photoview/photoview/labels/good%20first%20issue)
|
||||
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](https://github.com/photoview/photoview/issues?q=is%3Aopen+is%3Aissue+project%3Aphotoview%2Fphotoview%2F1+-label%3Aduplicate+-label%3Ainvalid+-label%3Awontfix+no%3Aassignee)
|
||||
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](https://github.com/photoview/photoview.github.io).
|
||||
- **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](https://github.com/photoview/photoview/compare)
|
||||
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](https://github.com/photoview/photoview.github.io).
|
||||
|
||||
## 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](./LICENSE.txt). 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](https://github.com/photoview/photoview.github.io),
|
||||
[issues](https://github.com/photoview/photoview/issues), [PRs](https://github.com/photoview/photoview/pulls),
|
||||
and [discussions](https://github.com/photoview/photoview/discussions).
|
||||
- We have the [Discord server](https://discord.gg/jQ392948u9) 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.
|
||||
13
README.md
13
README.md
|
|
@ -32,6 +32,7 @@ Password: **demo**
|
|||
- [Why yet another self-hosted photo gallery](#why-yet-another-self-hosted-photo-gallery)
|
||||
- [Getting started — Setup with Docker](#getting-started--setup-with-docker)
|
||||
- [Advanced setup](#advanced-setup)
|
||||
- [Contributing](#contributing)
|
||||
- [Set up development environment](#set-up-development-environment)
|
||||
- [Sponsors](#sponsors)
|
||||
|
||||
|
|
@ -156,6 +157,18 @@ Possible ways of securing a self-hosted service might be (but not limited to):
|
|||
|
||||
Setting up and configuring of all these protections depends on and requires a lot of info about your local network and self-hosted services. Based on this info, the configuration flow and resulting services architecture might differ a lot between cases. That is why in the scope of this project, we can only provide you with this high-level list of possible ways of webservice protection. You'll need to investigate them, find the best combination and configuration for your case, and take responsibility to configure everything in the correct and consistent way. We cannot provide you support for such highly secured setups, as a lot of things might work differently because of security limitations.
|
||||
|
||||
## Contributing
|
||||
|
||||
🎉 First off, thanks for your interest in contribution! 🎉
|
||||
|
||||
This project is a result of hard work, and it's great to see you interested in contributing.
|
||||
Contributions are not just about code — you can help in many ways!
|
||||
|
||||
Before you start, please take a moment to read our [Contributing guide](./CONTRIBUTING.md).
|
||||
It includes information on our code of conduct, the process for submitting pull requests, and more.
|
||||
|
||||
Remember, every contribution counts. Let's make this project better together! 💪
|
||||
|
||||
## Set up development environment
|
||||
|
||||
### Local setup
|
||||
|
|
|
|||
Loading…
Reference in New Issue