bernhard

How to submit Pull Requests to the ProcessWire Core

Recommended Posts

1) Setup the necessary GIT Repos

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

Q4psooY.png

 

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

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

fUZ7RZf.png

 

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

PZCE7EY.png

Now fetch the upstream:

git fetch upstream

c9odX7I.png

 

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:

e9hQU9e.png

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:

6EEl1CF.png

So we do what git tells us:

git checkout -b dev

3rGxydN.png

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

tId2kAC.png

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:

veKgQiE.png

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:

nGgbnry.png

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.

7c7dlta.png

  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:

ECGKNga.gif

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:

C7LvMZL.png

Just saying 😉 

 

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

pcYuFjb.png

Or if you prefer you can also open the diff:

0j0Wkt0.png

The Result:

QxKnhUZ.png

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

v0XEC0a.png

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

P76eAjl.png

 

4) Submitting the PR

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

git push -u origin FieldtypeFloat-comments

sBKbj2Y.png

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:

LiUE0Ab.png

 

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

QSBzIsU.png

 

Check if everything is correct:

M8pnWN9.png

 

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

ZFMeD1W.png

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

MHOUTen.png

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

i8tu96G.png

git merge upstream/dev

VNml98s.png

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

wzdHfFs.png

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

  • Like 13
  • Thanks 1

Share this post


Link to post
Share on other sites

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.

  • Like 4

Share this post


Link to post
Share on other sites

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 😉 

  • Like 1

Share this post


Link to post
Share on other sites

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

  • Like 1

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.