There is many info out there for first point, even a wiki article from phpBB itself, wich is kinda outdated and over-complicated in some places.
So I have learned all needed steps and want to share them with all people who are willing to to the requests themselves, but don't know how.
This tutorial wil be step by step
How to create pull requests for core events
Step 1: Register on GitHub
This step needs to be done once.
We should start with registering on Github. If you are already registered, skip this step and just login.
Go to GitHub and enter your credentials. Sign up. You can choose "Free" as payment option and don't need to check "Help me set up an organisation next". Glick on "Finish Signup" and everything is done there. You can and should verify your account on your email address though.
Step 2: Fork phpBB repository
This step needs to be done once.
Go to the official phpBB repository and fork it. That means you will create a version of this inside your own account, wich is like your own copy
You have to simply click on
It will take a few seconds, then you will have your own fork of phpBB where you can do whatever you want (:
Step 3: Set up your development environment
This step needs to be done once.
You need Git locally on your pc to do all the stuff. What tool you want to use for that depends on your operating system and your preferences. You need to install something that provides a Git Shell (this is a console for Git).
I am using GitHub for Windows wich includes a shell, so screenshots will be with this. But you can choose any other tool you want. Have a look in the topic [Info] Extension Writer Tools in section "Source Control (Git) Tools" for possible options.
If you have installed it, don't forget to login there with your GitHub account. In Github for Windows you just have to open the program and login. You can keep this window open.
When you have installed Git, you can get the forked repository to your local system. For that, just click on
Other option is to do it with command line. Open the Shell and navigate (with command
cd "path") to the folder where you want to store it. Then do the following. I have marked the important line:The link should be the one you can get on your repository under "HTTPS clone URL":
Greetings, you have finished setting everything up for doing pull requests!
Now comes the important part.
Step 4: Create a ticket for your event request
The first step you need to to when changing ANYTHING to phpBB is create a ticket. Nothing will be changed when there isn't a request for that. Even if you are requester and changer
That's an important rule to keep track of development changes.So go to phpBB Bug Tracker and login. You can use your phpbb.com login.
Click on "Create" to create a new ticket. We need to fill in the data now.
- Choose "Improvement" as issue type
- Add a short and understandable title for you ticket. For example: "Add core events on mcp_queue for approval and disapproval"
- Choose priority "Minor"
- Choose "Events" as component
- Affected Versions should be the latest release phpBB version where the event is still missing. So at the moment it is 3.1.2
- Description should be a text explaining what events you want to add and WHY you need them.
- Environment should contain informations about your system, but isn't really important for event requests, but more for bugs.
When you are finished, click on "Create". On the popup notification you can select the link to go the ticket. It now has a number. Mine is
PHPBB3-13537. You should keep that, this is very important.The ticket is ready, so we can start changing the files now.
Step 5: Setting up the local branch for your ticket
Okay. We need to do some command line stuff now. We need to follow the steps of the wiki article in section "Bug fixing", but I'll combine them here in the tutorial, so you don't have to read it there.
First, navigate inside the local repository in the shell. You should have that still open, so you just need to type
cd .\phpbb. After that, you should see a color-highlighted word behind the folder name. This is the name of the current branch: We want to do the event request for 3.1, so we need "3.1.x", wich is the name of this version.
Write the following line for that:
git checkout 3.1.x.It should take a few seconds to update all files, then the last line should be with colored "3.1.x".
This is the base where we start the new code. To do that, we need the branch for our ticket.
We create it with:
git branch ticket/13537, where 13537 should be your own ticket number.To switch to the new branch we do
git checkout ticket/13537.Now your console should look like this:
Step 6: Make file changes. Add the events
Okay. now you can add your events and do any changes that are needed for that. The files are inside the phpBB folder of your repository, so on my environment
D:\test\phpbb\phpBB.Just open the files inside it and adjust them with any IDE you want.
You need to take care of the following things:
- Add the right
@since VERSIONto the docblock of your event. If you don't know wich is the next released version, you can ask in webchat on channel #phpbb-dev or you can look into latest other event requests. - Don't forget to add the global
$phpbb_dispatcherat start of the function if it is not there already - Don't break the code sniffer. No empty lines with tabs inside, no double empty lines, no
$infront of variable name in the doc block - Important: If you add a style event, you have to add the description of your file manually to the file
D:\test\phpbb\phpBB\docs\events.mdin your repository. Just copy'n'paste a fitting description there, and make sure it is ordered alphabetically. In php events the description is automatically generated from the docblock comment
Code: Select all
/**
* Perform additional actions during post(s) approval
*
* @event core.approve_posts_after
* @var string action Variable containing the action we perform on the posts ('approve' or 'restore')
* @var array post_info Array containing info for all posts being approved
* @var array topic_info Array containing info for all parent topics of the posts
* @var int num_topics Variable containing number of topics
* @var bool notify_poster Variable telling if the post should be notified or not
* @var string success_msg Variable containing the language key for the success message
* @var string redirect Variable containing the redirect url
* @since 3.1.4-RC1
*/
$vars = array(
'action',
'post_info',
'topic_info',
'num_topics',
'notify_poster',
'success_msg',
'redirect',
);
extract($phpbb_dispatcher->trigger_event('core.approve_posts_after', compact($vars)));Then continue with the next step.
Step 7: Commit your changes to your repository
Okay. we have altered the files, now we need to commit them and push them to our ticket branch in our repository.
First, we need to add all files we have changed so that Git knows what to checkin.
Use this command:
git add <file>, where <file> should be path to the file name. To make it easy, you can press TAB on your keyboard, wich is suggesting folders and files for you.In my case, the only file changed is mcp_queue.php, so I use:
git add .\phpBB\includes\mcp\mcp_queue.phpNow there should be some green numbers behind your ticket branch name in the console.
For every file you add, the number in the middle should increase by one. Should look like this:
When all files are added, we need to commit them. The commit message should look like this
Code: Select all
[ticket/13537] Add core events on mcp_queue for approval and disapproval
Events added for the functions approve_posts(), approve_topics()
and disapprove_posts() in mcp_queue.php, so that you can send notifications
during approval and disapproval.
PHPBB3-13537Then an empty line. Followed by the longer description. Just write what you have done to describe it better. Make sure, no line is longer than 79 characters!
Then an empty line, followed by your full ticket ID, with the PHPBB3 in front.
This schema is not optional, it is required!
If you are using GitHub for windows like me, it will be difficult to get the line breaks correct, so here is what I do: I write the text in a texteditor before, so that it is easily copy'n'pasteable.
Then we do the commit. To get the empty lines there is a trick. Use "-m" (the message flag) for each new block, so the whole statement looks like this:
git commit -m "[ticket/13537] Add core events on mcp_queue for approval and disapproval" -m "Events added for the functions approve_posts(), approve_topics()
and disapprove_posts() in mcp_queue.php, so that you can send notifications
during approval and disapproval." -m "PHPBB3-13537"The easiest way (for me to insert) this is start typing
git commit -m ", then I copy the header line from my text editor and paste it (with rightclick), then type " -m ", copy the description text, even with line breaks, insert it, type " -m " and paste the last block, the ticket number. Now the type the missing " and press Enter and Enter again. The commit should be done now.Information: The steps of adding files and doing the commit messages can be simplified with Git Hooks provided by phpBB. You simply need to install them and then use
git commit -a and then type the message when prompted. This will automatically add the [ticket/1111] and PHPBB3-1111 parts to your commit message and check your commit message for errors before making the commit. No need to add files or any of that other stuff either (that's what the -a is for anyways) (Thanks to VSE for this information)After the comit (no matter wich of the two ways), you have to push the changes to GitHub.
Git tells you now what you have checked in and wich changes you made. The green numbers should be gone.
We are nearly finished with git now
One last line is needed.To push the commited files to your online repository, use:
git push origin ticket/13537(Remember to use your own ticket number)
Git should be finished now. It should look like this:
Step 8: Create the pull request
Now that we have adjusted our repository, we need to tell phpBB that they should include it. To do that, we need a pull request. The easiest way for that is to go on the GitHub wesite again, to your forked phpBB repository. If you refresh the site, there should be an information telling you that you may want to compare and pull request your branch:
Yes, we want that!
So click on the button. Now a window opens up. There needs to be a few adjustments. We need to choose
3.1.x as base branch, and we need to add the empty line before the ticket number in the discription again, wich strangely got stripped:If you have selected it, you can scroll down and see a cool comparision if you have done everything right, every change you made. If there is something wrong, you need to go back to Step 6, adjust the files, and add the changed files again with git add and all the stuff following, including the commit and push.
If everything is correct, we click
Wow, this is kinda cool. Now nearly everything is done! Your pull request is open, you can write something in the conversation there or simply wait and see if travis tests don't fail
But one last step is missing. Yeah, right, the ticket.
Step 9: Link your pull request as patch for the ticket
We need to tell the phpBB developers, that we made a "Fix" for this ticket. So go to the ticket in the Bug Tracker again, and click on
We need to insert the url of our pull request there. Just copy it from the browser of your GitHub pull request. It looks like this:
https://github.com/phpbb/phpbb/pull/3326For the comment I just add the description text of my commit.
When you click on submit, the status of the ticket should be changed to "Awaiting Patch Review" and your pull request is added.
Now you are done. And mentally done as well, if it is the first time for you I would guess
Keep an eye open on your travis tests. If they go read, you may need to adjust something. Also keep an eye open on questions on your pull requests, there may will be a discussion.
Keep in mind to make your events in a way they will be useful for others too.
(Step 10:) Do additional checkins to your pull request
This step is optional.
If a developer ask you for fixes or adjustments to your pull request, or if you want to change something yourself, it is very easy to do it.
You can continue to commit and push changes to your repo like described above, just follow the lines of Steps 6-7. Any new commit should have it's on commit message, fitting the commit message rules, with ticket id, header and a description what you have changed now. After you have done the push to your repository, the pull request is updated automatically, nothing to do there. This can be repeated as often as you want, until the pull request gets merged be phpBB.
The End
If you have any suggestions for the tutorial, tell me!
Also if you have questions, this topic may be the right place as well.
