Pull Requests

Michael Mayer edited this page Nov 24, 2018 · 17 revisions

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:
    • make test
  • 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 fmt to 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 #1234:
    • 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.

Next: Code Quality

Back to Getting Started

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.