Contributing to Blue Twilight development

The Blue Twilight PHP photo gallery is an open-source product. Whilst I maintain the app and manage the releases, I welcome contributions from the community.

The source code is freely available from the project’s website on Gitea. Anyone can download and modify the code for their own needs.

If you are willing to submit your changes back to the project for everyone to enjoy, I will provide hosting for your own custom Git repository on my Gitea system. You can then fork the repository and make your changes. When you’re ready, submit a pull request and I can include them in the main release.

Do you want to contribute to the project but don’t know where to start? Why not check out the list of issues and pick something to work on?

How to Contribute

If you wish to contribute to the project, please follow the steps outlined below.

Register an account on Gitea

To begin, you need an account on Gitea. You can create a new account by clicking the Register link at the top of the page.

If you wish to use a social media account (Facebook, Twitter, Github and Bitbucket are supported) you can use the Sign In link and click on the Facebook, Twitter, Github or Bitbucket icon at the bottom of the page. Once you have logged in to your social media account, please set a password to access your account directly.

Screenshot of the Apps by Andy Gitea registration screen
The Gitea registration screen asks for minimal details and typically only takes a couple of minutes to register a new account.

Set up a repository

By default, Gitea does not allow new users to create repositories. When you have registered an account, please contact me with your username and/or e-mail address, and I will grant you access to create a repository.

After I’ve let you know you can now create a repository, fork the Blue Twilight repository.

Fork the Blue Twilight repository

To fork the repository, browse to the Blue Twilight project on Gitea. Click the “Fork” button in the top right corner.

Screenshot of the Gitea fork repository form
Gitea will provide you with a “new repository” form with all details already completed.

Click the “Fork Repository” button to create your copy of the Blue Twilight repository.

Pull the repository

You can now download your own repository using your favourite Git client (CLI, SourceTree, etc.)

Your unique URL is displayed in Gitea on the right-hand side above the list of commits. My Gitea server supports HTTPS or SSH (recommended.)

Create a branch and make your changes

It’s good practice to make your changes on a separate branch. When you submit your pull request, you will submit only the changes specifically made in that branch.

If you are unfamiliar with branching, refer to the Git documentation.

I personally prefer to name my branches with either a “bugfix/” or “feature/” prefix, depending on the type of change you are making. I also prefix the branch name with the issue number for reference. For example:

  • If I’m fixing bug #28, my branch name would be: bugfix/28-description-of-the-bug
  • If I’m implementing a new feature #93, my branch name would be: feature/93-description-of-the-feature

If you do not have an issue number (e.g. it’s one of your own changes that isn’t logged in Gitea), your branch name would be the same just without the number.

On your branch, make the changes you want to make to the code and commit them.

Push your changes

Git will only commit changes to your local copy of the repository. To make them available to your Gitea-hosted repository (and therefore available to submit in a pull request) you need to “push” your changes.

All decent Git clients have a “push” option, or your can use the git push command.

It is good practice to always push your changes after you have committed. If your local repository becomes damaged or lost, your changes are safe on my server. SourceTree has an option you can enable to automatically push every time you commit.

Submit your pull request

When you are ready to submit your changes for me to include in the main release, you need to create a pull request.

From your repository’s page in Gitea, click “Pull Requests”, followed by “New Pull Request.”

Screenshot of Gitea showing a new pull request

From the “compare” drop-down, select the branch in your repository that contains your changes.

Give your pull request a descriptive title and description, referencing any issue numbers if necessary. Ensure your description contains an explanation of what your changes are designed to do.

Screenshot showing the details to enter in a new pull request

Click the “Create Pull Request” button. Your pull request will be submitted, and I will get a notification e-mail to approve it.

Look out for your name and details of your changes in the release notes!

« Back to Blue Twilight