Contributing: You can do it too!

[mrgoldy]

So lately I've been playing with the idea on how to make contributing to phpBB more accessible.
As I see quite a few people trying to contribute, but not following the workflow required by phpBB.
Some examples are wrong branch names or incorrect commit messages.

That got me wondering what would be possible to make it easier on everyone, and what else could be included.
As git has endless possibilities and it is steep hill to climb, I myself barely know and understand 5% of the possibilities.
So 3Di and I made a Bash script (studio) that handles most of the common tasks that would be needed to contribute to phpBB development.

Actual development commands are included, such as creating a new ticket branch, commiting to it, etc..
But we've also included a way to test Pull Requests (PR's) by others, nice and easy.
That way PR's can be tested by more people to find potential bugs faster, especially in bigger PR's.

Requirements

• GitHub Account
  You will need to have a GitHub account.
  If you do not have one already, you can create one by Joining GitHub.
• Git
  You will need to have Git installed aswell.
  Getting started: Installing Git or download: Windows | Mac | Linux
• PHP
  You will need to have PHP installed aswell and made available in the Command Line Interface (CLI).
  Command Line PHP on Microsoft Windows
• Local environment
  You will need to have a local test environment (localhost).
  There are a few articles out there that you can follow.
  They might be slightly outdated but still should give you the gist of things:
  Running phpBB on localhost | Installing and setting up your own Web Server
• Test config
  In order for us to handle some of the commands for you, you will have to set up a test config,
  which will hold the information for the database connection (much like the config.php file).
  It should also include the $phpbb_functional_url.
  Test config | Functional URL | Example

Recommended

• A git interface
  TortoiseGit | GitKraken | GitHub Desktop
  These are all convenience tools when working with git on your desktop.
  They handle a lot of the common tasks for you when developing code, such as push, pull, checkout, etc..
  Especially in the beginning these might make life easier on you.
  Once you are more experienced and understand how things work, you can 'just' use the cli.

YOUR INPUT. It's been a while since we had to set these up for ourselves. So we do not remember all the common pitfalls. If you run into any problems, feel free to ask. Or if you've worked some common issues out yourself, even better, please share them so you save time for others and I can include them in this initial post. So feel free to contribute to this post.

Fork the repository
Now head over to the phpBB repository (repo): https://github.com/phpbb/phpbb
Make sure you are logged in to your GitHub account.
Then in the upper right corner, you can click on the Fork button.
Follow the process and you should end up being redirected to your own fork, eg: github.com/mrgoldy/phpbb

Clone the repository
Now head over to the localhost you've set up earlier, eg XAMPP or WAMPP.
Make sure you're inside the htdocs folder, or the respective folder for the localhost you've installed.
Then either create a new directory, eg phpbbfork, or not. But I would recommend creating a directory.
Otherwise the repository (repo) you are about to clone, might be entangled with other files in your htdocs.
Select the directory if you've created one, and right click on it (otherwise just right click the current window).
From the context menu select GitBash here..., which will open a command line interface.
Enter the following command: git clone https://github.com/mrgoldy/phpbb.git (replace mrgoldy with your username).
If you've created a directory, you want to append a single dot . to the command: git clone https://github.com/mrgoldy/phpbb.git .
If you've not created a directory, omit the . and it will create a new phpbb directory automatically.

Alternatively, if you've installed TortoiseGit, you can right click on the window and select Git clone...
Provide the URL https://github.com/mrgoldy/phpbb.git (replace mrgoldy with your username).
And make sure you have selected the desired directory, which if it doesn't exist already, is automatically created.

Place the files
Now it's time to place 2 files: test_config.php and studio.

The test_config.php file, as mentioned in the Requirements, needs to be placed in the tests folder.
So for me, the complete file path would be: C:\xampp\htdocs\phpbbfork\tests\test_config.php.
You can use the provided example to get you started.
Make sure to fill in your database information, with the database you've set up for your localhost.
And correct the $phpbb_functional_url if necessary, so for me it would be: http://localhost/phpbbfork/phpBB/.
This functional URL should point to the phpBB directory of your cloned fork.
And then replace everything before and including .../htdocs/ with http://localhost/.
This variable is necessary for the studio script to (re-)install the local board for you.

The studio file, will have to be placed in the root of your fork, not the phpBB root path you might be used to.
So for me, the complete file path would be: C:\xampp\htdocs\phpbbfork\studio.
So it's placed in the same directory as LICENSE.txt and README.md.

As you might have noticed, I did not include a file extension with the file.
That's for convienence later on, so the commands are a bit 'cleaner' and easier to use.
If you can not create or place the file without a file extension, give it the .sh (shell) extension.
You can either copy the file from the GitHub Gist I've created.
Or alternatively you can download and extract it from the attached archive:

studio.zip

(3.69 KiB) Downloaded 888 times

That's it!
Now you're good to go.
The initial set up might take some time, but it should be a one-time-deal.
The available commands and their respective explanation I will do in the next post.

[mrgoldy]

First you will have to open te command line interface (cli) in your fork's root.
The same way as described in the previous post when cloning the repository (repo).

All commands that are available in the studio script, start with sh studio <command>.
All commands that have parameters, the parameters are completely optional!
Meaning that if you do not fill them in, you will be guided through the process when calling the bare command.
So you're explicitly asked what the parameter values should be for each parameter available.

If you were unable to save the script without a file extension and had to append .sh, you will have to append it in the command aswell.
Meaning that all the commands start with sh studio.sh <command>, but in the examples below we will use the first option.

The commands below are not listed in any particular order, but it's recommended to run the setup command first.
Especially cause this command only has to be ran once, and ensures you have to correct line endings setting.
Which is especially important if you are on Windows, which has a different default setting!

It is possible to get a list of available commands by only typing sh studio.

Overview

• Common commands
  setup
  update
  switch
  install (which I apparently forgot in the menu, sorry)
   
• Testing commands
  test-pr
   
• Developing commands
  create
  commit
  amend
  clean

___________________________________________________________________________

setup
Command: sh studio setup
Parameters: "Name" "Email" (both optional)
Example: sh studio setup mrgoldy [email protected]
Explanation:
This command should only have to be ran once, but it is not required for the rest of the studio script to work.
The config settings that are set are the following:
        Your git's user.name. If you do not provide any, it will not be set or overwritten. (phpBB Docs and reference)
        Your git's user.email. If you do not provide any, it will not be set or overwritten. (phpBB Docs and reference)
        Set git's core.autocrlf to false as per phpBB requirements. (phpBB Docs and reference)
        Add upstream as a remote, if it didn't exist already. (phpBB Docs and reference)
                origin: This remote name is commonly used for your personal repository (https://github.com/mrgoldy/phpbb.git).
                upstream: This remote name is commonly used for the original repository (https://github.com/phpbb/phpbb.git).

update
Command: sh studio update
Parameters: none
Example: sh studio update
Explanation:
Changes made to the phpBB GitHub repository (https://github.com/phpbb/phpbb) are not automatically made to your fork and clone.
Your fork is your repository on GitHub (https://github.com/mrgoldy/phpbb).
Your clone are the files on your computer (C:\xampp\htdocs\phpbbfork).
So it is important that those stay up-to-date with any changes made to phpBB's repository, and you will have to do that yourself.
This can be done with the sh studio update command.
First it pulls everything from the phpBB repository, so your clone is updated.
Then it pushes your clone, so your fork is updated.

switch
Command: sh studio switch
Parameters: "Branch" (optional) (3.2.x|3.3.x|master)
Example: sh studio switch 3.2.x | sh studio switch 3.3.x | sh studio switch master
Explanation:
Currently there are three 'base' branches in phpBB: master, 3.3.x and 3.2.x
These hold the code for their respective latest version, at the time of writing: 4.0.0-a1, 3.3.0 and 3.2.9
Each branch has its own code, database setup and dependencies (the vendor folder).
This command takes care of the code and dependencies, for the database setup you will have to use the install command.
Once done, it will automatically ask you if you also want to install the board, which you can answer with Yes or No.
For the people interested in what is exactly doing:
git checkout master; git checkout <branch>; cd phpBB; php composer.phar install; cd ../
(phpBB Docs and reference)

install
Command: sh studio install
Parameters: none
Example: sh studio install
Explanation:
This will take care of the 'database setup' of your local board.
It ensures all the correct tables are installed, with the correct columns and default values.
For this command the $phpbb_functional_url is required in the test_config.php file.
This ensures that we can re-install the board, overriding an existing installation.
To accomplish this, the studio script makes use of the functional tests provided by phpBB,
which do not have to be of further concern to you for the sake of using the studio script.
The credentials for the admin account on the local board are:
username: admin
password: adminadmin

___________________________________________________________________________

test-pr
Command: sh studio test-pr
Parameters: "PR number" (optional)
Example: sh studio test-pr 5920
Explanation:
Now if actual code development is not your cup of tea, that does not mean you can not contribute!
You can head over to the phpBB's Pull Request list and choose a PR you want to test.
If you click on one of the PR's, you can see the Pull Request number (the identifier) in the url bar of your browser.
For example, the url will be: https://github.com/phpbb/phpbb/pull/5920.
Then the identifier of that Pull Request, the PR number, will be 5920.

It will then automatically install the dependencies for that PR (the vendor folder).
Once done, it will automatically ask you if you also want to install the board, which you can answer with Yes or No.

You will now be in a "detached HEAD" state. Git will also post a notice about it (before the dependencies message).
This will also be visible in the command line, cause it now displays ((7149349e25...)).
This isn't really to any concern to you and nothing for you to worry about.
But to quickly and simply explain it: it means that git does not recognize what branch you are on and is not sure what to do with it.
Once you are done testing or want to perform any different commands, use git switch -.
This will switch you back to the state your local clone was in before testing.
You might notice the ((7149349e25...)) has changed back to (master) (or what branch you were on).
Please do note that the installed board and its dependencies are not automatically reverted back.

___________________________________________________________________________

Let's quickly talk a little bit about how all of this works.
The phpBB repository on GitHub contains all the current code, that is actually redistributed.
You do not have permission to alter any of the code directly, for obvious reasons.
So in order to still make changes to phpBB's code, you've created a copy: your fork.
You can now make any changes you want to that code, and then propose them as a Pull Request.

You will have to perform these changes on your local clone of your fork (the files on your computer).
You will then have to commit these changes (as a simple word: "save").
But then the changes are only done locally, on your computer, and are not yet on your fork.
So you will have to push the changes from your clone to your fork (as a simple word: "upload").
Once your fork contains the changes aswell, you can compare that against the phpBB repository: the PR.

You can read more about all of this in the phpBB Git Documenation.

create
Command: sh studio create
Parameters: "Base branch" "Ticket number" (both optional)
Example: sh studio create 3.2.x 12345
Explanation:
phpBB has made it so, that changes made by anyone are not directly made on a branch, eg 3.2.x.
If that were the case, it would become harder to track who made which changes for what reason.
So first there has to be a ticket in the phpBB Tracker, which allows for some oversight.
Once a ticket has been created, eg. for a bug or a feature, you will also know the "Ticket number".
As an example, recently this ticket has been created: phpBB 3 / PHPBB3-16426.
The number for this specific ticket is: 16426.

Then you will have to decide to what version this ticket belongs, is it aimed for 3.2.x, 3.3.x or master (4.0.0-a1)?
As a rule of thumb (at the time of writing) you can use:
        master: New features
        3.3.x: Bug fixes and minor improvements
        3.2.x: Bug fixes

Once you know the "base branch" and the "ticket number", you can go ahead a create a branch.
This branch as to be created from the correct base branch, and follow a naming convention: ticket/16426.
The sh studio create command does all of this for you, to ensure you have the correct setup.

commit
Command: sh studio commit
Parameters: "Commit message" (optional)
Example: sh studio commit "Implement new array syntax for UCP"
Explanation:
Make sure when making changes, that you are on the correct ticket branch, created with sh studio create.

If you have made changes to your local files, you will have to "save" and "upload" them to your repository.
The git terms for these actions are commit and push respectively.

This command will automatically save any changes made to existing files in your clone.
However, if you've created any new files, these are not automatically added and git is not aware of them.
This is where TortoiseGit or any other tool is convenient, so you can more easily add extra files to the repository.
Alternatively you can use the git command: git add <the file path>.
For example, if we wanted to add (the already existing) config.php: git add phpBB/config.php.
The path is relative to the root directory of your clone, the directory where this studio script should be located.

Now, when saving these changes, you have to provide a required "commit message".
Commit messages should also follow a precise layout, for all the automated actions tied to commits to work.
You can compare this to the "edit reason" when editing a post in phpBB.

This command handles the layout of the commit message, you only have to provide a meaningful and concise reason.
The reason you provide should try and quickly explain what it is you're changing, with no more than 64 characters!
Once done, this command deducts the ticket number from the branch you are on, eg ticket/16426: 16426.
It then commits and pushes ("save" & "upload") your changes with the following commit message:

Code: Select all

[ticket/16426] Add default setting for search character limit
 
PHPBB3-16426

Afterwards, it will explain how you can create a Pull Request.
It will also ask you if you want to create a Pull Request right away, which you can answer with Yes or No.
If you do want to create a PR, it will open a new browser tab from where you can create it.
It will automatically have to correct base branch selected, you only have to edit the PR template (the message).

amend
Command: sh studio amend
Parameters: "New commit message" (optional)
Example: sh studio amend "My new commit message"
Explanation:
If you've made all your commits using the studio script, you will probably not need this command.
It is more a situational and conveniene command, that allows to alter the last commit message.
For example, when you have an error in there that made the tests fail.

Make sure you are on one of your ticket branches, eg ticket/16426.
This command will then display your last commit message, and ask what the new one should be.
Once again, you only have to provide the 'reason', the rest of the commit message is automatically created.

clean
Command: sh studio clean
Parameters: none
Example: sh studio clean
Explanation:
This command is for convenience aswell, and not required to be ran once at all.
But it might be useful for some, especially once you've racked up quite a few Pull Requests.
Your fork and clone will then have a lot of ticket branches, which might already be merged into the phpBB repository.
These branches are no longer of any use and can savely be removed from your own repository.
This command will delete all the merged branches both in your clone and in your fork.
Note: the first time you run this, it might show a few git errors, due to the fact that your clone and fork might be out of sync.
For example, if you already deleted the ticket branch on your fork, but not on your clone.

___________________________________________________________________________

The end
These are all the currently available command in the studio script!
We hope it helps out anyone willing to contribute in any way, shape or form.

If you have any suggestions, tips or notes about the script or this topic, feel free to post a reply!

Happy contributing,
The Studio

[P_I]

WOW!! As a very occasional contributor to phpBB this looks very helpful and needed. Looking forward to giving it a whirl and providing feedback.

[hanakin]

recommend abandoning tortoise git for something more user friendly. even the GitHub app is better IMHO or look at gitkraken. both of which are free

[mrgoldy]

We’ve been using it for several years and never had any problems. Nor is it really the purpose of this topic, as it is aimed towards the studio script.

But if you give me some referencing links I’ll list them.

[3Di]

And finally I prepared a cup of coffee (Italian espresso) and read the whole topic, I was impressed by the exhaustive and lucid explanation of all this in detail made by mrgoldy to whom I give my sincerest gratitude, I certainly would not have been able to. We at The Studio hope that this will increase the number of people who will be involved in contributing to the phpBB project, even if only occasionally.

[mrgoldy]

I hope it was a double espresso, as I just realised I did rack up two quite long posts.

I've added detailed explanations and examples of all the commands available.
If you have any suggestions or tips in regards to what needs to be explained better/aswell/differently, please let me know.

Happy easter!

[hanakin]

https://www.gitkraken.com/
https://desktop.github.com/

For mac there is also https://www.git-tower.com/, but its not free

P.S. mrgoldy, I am sorry for you that you have been stuck using tortise

[DavidIQ]

Personally SmartGit has served me well for several years now when working with Github. Easy to use and understand.

At work it's just command line git stuff since it's all done through an on-prem GitLab instance, but we do have posh-git installed on all machines to help with visualizing some of the git stuff (current branch, edited files, branch status, etc.) in PowerShell.

[HD321kbps]

Good alternative Sublime Merge from Sublime Text developers