Return to development overview

We hold our code in a github repository. To make a change to the codebase:

  • Clone the relevant repository.
  • Check out the main branch.
  • Work on the changes you want to make locally, and test them.
  • Create a new branch.
  • Check your changes into the new branch.
  • Ask the team, or at least another developer, to review the changes.
  • Merge the changes from your branch into the main branch.
  • Delete your branch.

There are various ways of working with wordpress and github concerning where you check out the code.

When you have a site running in wordpress using – for example – the localWP system – there will be a ‘Local Sites’ directory, and in that there will be all your sites. In each site there will be an app/public/wp-contents directory, and within that a plugins directory. This is where our plugins live, and if you checked out the root of the (for example) u3a-siteworks-core github repository into this plugins directory, the plugin would be present in the site. You could then edit the plugin by opening the u3s-siteworks-core directory in vscode. When finished, you can push the directory back to github in a new branch.

Another way of working would be to check out the github repositories to a directory of your choice. Copy the whole directory for the plugin into the plugins directory, and work on that copy. When you are happy with the changes, copy it back to the checkout directory and push that back to github. This method allows you to use diff and verify that you know exactly what changes you are delivering. You should of course use ‘git status’ and ‘git diff’ before delivering too.

We recommend using local which can be downloaded here https://localwp.com/ . This provides the environment around the wordpress editor such that the site can be tested live using a local connection without having to provide a web server.

The vscode integration with github is documented in the vscode page. If you want to use the command line, there are lots of useful commands, but a few very key ones are:

In a browser, go to the github repository you want to clone – click on the ‘code’ button and copy the https url of the repository, then on your command line, in a suitable base directory:

git clone <paste the url> – this clones the repo locally (branch main or master).

git branch – this tells you what branch you cloned.

git pull origin <branchname> pulls the latest code to a branch you have already cloned (use this if the branch has been updated by someone else since you cloned it)

git branch <branchname> – creates a new branch of that name- Note this starts out as a copy of the branch you currently have checked out.

git checkout <branchname> – switches locally to the branch of that name.

git status – lists the files you have changed or created. Red files are ones you have changed locally, but not ‘added’ yet.

git diff – gives a full diff of all the changes made.

git diff <filename> – gives a diff of just that file

git add <filename> ‘adds’ a file – that is to say adds it to a set which will be pushed when you push to the remote branch. When you do git status, these files are now green.

git commit -m “message” – commits all the files you ‘added’ earlier – with a message attached to the commit.

git push origin <branchname> Finally really does post off all the changes you made in the commit to the repository. You can now go back to the browser and see the newly created branch.

There are many other commands which are less used:

git stash which will hide all the changes you made locally temporarily, so you can see what the repo looked like before you started. ‘git stash pop’ brings them all back.

git reset HEAD –hard – dangerous – this overwrites all your local changes and switches your branch back to look like the remote repository.

Having vscode and localWP available means that changes can be made and tested directly on a live local website, so the code/test cycle is quite fast. There are no specific acceptance test criteria, so the developer needs to be confident that the code works by a combination of manual testing (including limits testing) and if necessary, setting breakpoints and walking through the new code to ensure that it performs as expected. This last step is particularly needed for plugin code, as you can often find that the code you wrote is called where you expected it to be, but also where you might not have expected it to be called – possibly with empty parameters.