How to work with Pull Requests¶
Because we want to create the best possible product for our users, we have a set of guidelines which ensure that all source code contributions are acceptable. They are not intended as a filter or barrier to participation. If you are unfamiliar with open source development on GitHub, we will help you. Our [[documentation]] is mostly kept outside of the main repository so that the commit log doesn't get cluttered with lots of small text changes.
To submit new code, follow these steps:
Fork our main repository¶
- Click the Fork button in the header of our main repository
- Clone the forked repository on your local computer:
git clone https://github.com/[your username]/photoprism
- Connect your local to our "upstream" main repository by adding it as a remote:
git remote add upstream https://github.com/photoprism/photoprism.git
- Create a new branch from
develop- it should have a short and descriptive name (not "patch-1") that does not already exist, for example:
git checkout -b feature/your_feature_name
- See also https://guides.github.com/activities/forking/
Make your changes¶
- While you are working on it and your pull request is not merged yet, pull in changes from "upstream" often so that you stay up to date and there is a lower risk for merge conflicts:
git fetch upstream
git merge upstream/develop
- We recommend running tests after each change to make sure you didn't break anything:
- Add tests for any new code. If you have questions about how to do this, please ask in your pull request or on our mailing list.
- Please run
make fmtto ensure code is properly formatted according to our standards.
- If all tests are green and you see no other errors, commit your changes. To reference related GitHub issues, please end your commit message with the issue ID like
git status -s
git add .
git commit -m "Your commit message #1234"
When you’re ready...¶
- Sign the Contributor License Agreement (CLA).
- Verify you didn't forget to add / commit files (output should be empty):
git status -s
- Push all commits to your forked remote repository on GitHub:
git push -u origin feature/your_feature_name
- Create a pull request with a helpful description of what it does.
- Wait for our code review and fix remaining issues, if any.
- Write documentation if you are adding new features or changing functionality. It is hosted on docs.photoprism.org and automatically updates whenever changes are pushed to the repository.
Note: You can also create a pull request if your changes are not complete / working yet. Simply let us know that it is in progress, so that we don't try to merge it. We can help you with a code review or other feedback, if needed.