How to submit Pull Requests to the ProcessWire Core

[bernhard]

1) Setup the necessary GIT Repos

Fork ProcessWire: https://github.com/processwire/processwire

 

Clone your fork to your local dev environment (I named my folder processwire-fork):

git clone git@github.com:BernhardBaumrock/processwire.git .

 

To be able to keep the fork in sync with ProcessWire we need to set the upstream, because currently it only points to the fork:

git remote -v
// result:
origin  git@github.com:BernhardBaumrock/processwire.git (fetch)
origin  git@github.com:BernhardBaumrock/processwire.git (push)

git remote add upstream https://github.com/processwire/processwire.git

Now fetch the upstream:

git fetch upstream

 

As you can see we are still on the master branch (of the fork). We want to work on the dev branch. In VSCode you instantly see all the available branches and which branch you are on:

But you can also use the console:

git checkout origin/dev

Ok, as we did not have a local dev branch yet, we get this warning:

So we do what git tells us:

git checkout -b dev

We are almost ready to go and we can check if it is working by simply modifying the index.php file:

Nice! Index.php shows up in the git panel on the left side under "changes" and clicking on it we get a nice diff (if you haven't tried VSCode yet, give it a go and see the corresponding forum thread here).

 

2) Setup a running ProcessWire instance

Now that we have a fresh fork of ProcessWire we want to contribute something to the project. But how? We need to install ProcessWire first to test everything, right? But we don't want to copy over all edited files manually, do we? Symlinks to the rescue.

We just install ProcessWire in another folder (in my case I use /www/processwire) and then we replace the /wire folder of the running instance by a symlink to the wire folder inside the fork. Let's try that via CMD:

If you have your folders on the C:/ drive you might need to run CMD as admin.

We are ready for our first contribution! ? 

This is how my ProcessWire installation looks like:

Note these things:

1. We are inside "processwire", not "processwire-fork"
2. There is no .git folder, meaning this instance is not under version control
3. The wire folder is symlinked. And this folder IS under version control, but in another folder (processwire-fork)

If you want to contribute to something outside of the wire folder, just symlink these files as well (eg index.php or .htaccess)...

 

3) Example PR - Coding

You might have seen this discussion about FieldtypeDecimal for ProcessWire: https://github.com/processwire/processwire-requests/issues/126

I thought it would make sense to have at least a comment in FieldtypeFloat that you can run into troubles when using FieldtypeFloat in some situations. I then wanted to make a PR and since I don't do that every day it's always a kind of hurdle. That's also a reason why I created this tutorial, as a side note ? 

 

Ok, we want to add some comments to FieldtypeFloat, so we open up the forked repository of ProcessWire in VSCode. This is important! We work on the forked folder "processwire-fork" but we TEST everything in the browser from the test-instance in the folder "processwire". This might be a little confusing at first, but we are not working on a local project, we are working on the core.

1. We see that we are on the fork
2. In the folder is a clone of ProcessWire that is NOT installed yet
3. We are on the DEV branch and this branch is not yet uploaded to our git account (the cloud symbol shows this)

 

Important: Before you start your changes you always need to make sure that you have the latest version of ProcessWire in your folder! This is done by pulling a branch from your upstream. If you want to work on different contributions it might make sense to create a separate branch for each modification. See this example:

The commands are:

git checkout -b FieldtypeFloat-comments
git pull upstream dev

Using VSCode it might be easier to create new branches or switch between existing ones:

Just saying ? 

 

Now the changes: We open FieldtypeFloat.php and add our comments. We instantly see our changes in VSCode:

Or if you prefer you can also open the diff:

The Result:

When we are happy with our changes we can commit them (either using the VSCode UI or the command line):

git add .
git commit -m "your commit message"

 

4) Submitting the PR

First, we need to upload the new branch to our forked repo:

git push -u origin FieldtypeFloat-comments

See the first command and the comment what happens if you don't define the remote branch.

Now head over to your github account and click to create the PR:

 

Just make sure that you send your pull request to the dev branch!

 

Check if everything is correct:

 

And voilà: https://github.com/processwire/processwire/pull/130

 

That's how I do it. If you know better ways or have any suggestions for improvements please let me know ? 

 

-------------------- update -----------------------

5) Updating the fork

If you already have your setup and just want to grab the latest version of ProcessWire into your fork, this is what you have to do:

git fetch --all

As you can see it grabs the new dev version from the upstream repo. But if you go back to the running PW site's upgrades page you'll see that you are still on the old version. We need to merge the changes into our branch.

But before we do that, we make sure we are on our local dev branch:

git checkout dev

git merge upstream/dev

Now head over to your sites admin and you'll see that we merged the changes:

You can now continue by creating a new branch and working on it as shown in section 3.

[dotnetic]

Thank you @bernhard for another great tutorial. Written very well and very understandable.

[arjen]

Nice one @bernhard!

If you have a single remote you can also ...

git fetch

... first afterwards you can safely

git checkout dev

If you have multiple remotes you can ...

git checkout -b dev origin/dev

... in one command.

No creepy warning about being in detached HEAD mode.

[bernhard]

Thx arjen,

I like tutorials that show things step by step, including possible warnings, how to read and how to fix them. Shortcuts are nice when you have some experience but they can be a pain in tutorials...

Having said that, I also have to admit that I'm still just scratching the surface of GIT and I like to do things step-by-step myself ? 

[kongondo]

Wow! s'all am sayin ??

[gmclelland]

Thanks bernard, great writeup!

In case it helps someone else, here's the guides I use(which are very similar)

1. https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/ 
2. https://akrabat.com/the-beginners-guide-to-rebasing-your-pr/ - the followup

[bernhard]

I've added a section about how to grab the latest updates of processwire when you already have the setup shown in this tutorial.