Extension Developers; Show us your workflow!

Set up

• OSX (although I came from windows ages ago and switched to Ubuntu until a year ago).
• PHPStorm with open source license (yes .. one benefit of doing that).
• A regular macbook pro from last year with a memory upgrade, 13" no bar, but lots of foo ?.
• Laravel Valet for serving sites, please note I have done everything else like developing on a remote server, docker, vagrant and local webservers.
• Local Mariadb for database.
• PHP 7.1 installed locally using brew.
• The best terminal combination.
• Sequel Pro for viewing the databases.
• yarn installed via brew.

Now that's the software and tools. I have one flarum installation under Sites if you create that on OSX under your home directory it gets a fancy icon. That one flarum installation is a simple ~Sites$ composer create-project flarum/flarum flarum and then with a modified composer.json that points to the workbench subdirectory, every extension I work on lives there.

The workbench method is explained here. Please note that @Franz studio is based on the same method.

Some additionals based on the above

Your Operating System is important. One of the reasons to use a Linux based OS is file case sensitivity and directory separators. Okay, technical terms, this only is problematic if your code will run on computers (read webservers) that do not run Windows, which is very much likely based on the market share. Please note OSX also has to be configured to be case sensitive.

PHPStorm is an IDE. Lots of people will tell you that using an IDE is for noobs or whatever. I actually started coding on dreamweaver and then on a simple text editor called Kate. In the end you have to pick the tool that is best for you, mastering one takes a lot of time however. And tools that increase your coding efficiency always make more sense than those that do not. Important features of PHPStorm I value:

• Tells me when code is wrong, also for specific versions of js or php.
• Helps me go through my code easily by clicking any class.
• Hints and autocompletes classes, properties and arguments.
• Can do tasks I hate to do myself, Gulping, Unit testing, composer tasks (since version 2017.2), Git.
• Offers plenty of plugins and themes. Having an editor that pleases you increases your chances of finding all of it enjoyable.

New extension

Every time I start a new extension this is my workflow:

• Have an idea, think a lot about it before you start.
• Discuss your concept with some people, get a good feeling about the goals even if they seem out of your reach.
• Come up with a name, yes.. I hardly ever start on an extension and afterwards rename it. Once published renaming an extension including namespaces etc is time you could have spent elsewhere.
• The decision whether to actually do work on an extension is a tough one, because the more you have the more you need to maintain. Nevertheless I sometimes start out of sheer excitement with the obvious risk of them not seeing a release (soon).
• Go to your version control ui, eg GitHub or GitLab and create a project on your namespace, for me that's flagrow. Make sure it's a clean one. Copy the url provided by the empty repository page, eg; git@github.com:flagrow/foo.git.
• Create a new directory inside workbench, go to your workbench and type git clone git@github.com:flagrow/foo.git which will create directory foo automatically. This let's Git know you are the proud owner of another git versioned directory and .. it adds a remote server to push changes to.
• Copy files from another extension, well .. because I'm lazy ? . Whenever I add files or directories phpstorm will add it to git; it will ask you about it.
  • .gitignore ignores files for git
  • composer.json specifies package name, description and dependencies
  • .editorconfig forces a specific indentation etc.
  • license.md in case it's MIT.
  • contributing.md
  • js/forum/package.json and js/forum/Gulpfile.js and js/forum/yarn.lock if the forum needs frontend work, replace forum with admin if I need admin work. Inside the Gulpfile.js I need to update the namespace.
  • src/Listeners/AddClientAssets.php most likely I'll need publishing js or less.
• Commit all this so you don't lose progress in case your computer takes off to mars git commit -am "first" then push this to the remote git push in case it tells you to define a default push branch simply follow instructions. Check your GitHub, GitLab or whatever repository page that it receives the data.

Now depending on the type of the extension I start writing the zeroes and ones (kidding here, yes rea11y). For extensions that do a lot of backend things I mostly start from that angle and work my way towards the browser. Thus the src/ directory is very often increasing in size within a matter of hours.

I've never had that I completed backend or frontend before doing work on the other. They go hand in hand. Frontend needs additional settings or model properties and backend needs to save information into the database.

Some notes during development I can think of;

• Once I work on the js directories, I go into them and run yarn which installs the node_modules.
• Now in phpstorm I right click the Gulpfile.js and "show gulp tasks" it now shows the task "watch" for that directory. Once double clicked phpstorm will take care of gulp watching your js files, up until you close the project.
• Regularly push changes, phpstorm asks you to add files if you want to. I allow phpstorm to do so as the .gitignore takes care of files I don't need. So a command like git commit -am "message here" is enough, the a flags tells git to add all changes (leaves out files that have not yet been added to git) and m allows you to add a commit message inline. Then push the commit(s) with git push.
• Keep chrome developer console open (disable cache if open in its settings) to disable browser cache.

Once the extension is coming together nicely I reconsider every feature I wanted to push into the initial release and start dropping everything that is simply too much in terms of additional work. Pushing out releases regularly helps at working with easy to complete tasks (agile anyone?).

Releasing

• Copy the readme.md from another extension and modify the information.
• Create a changelog.md and add the version I am about to release.
• Done? Double check that everything works (again).
• Don't forget to commit the changes.
• Go to packagist.org and publish your package. Set up the service in your GitHub/-Lab repository so that it sends webhooks to packagist on new tags, commits etc. It's called auto updating.
• If you know a ? able to install the dev-master without being a ? ask her to do a test run.
• Optionally create a gif, I use Licecap for that. Update it in your readme. I mostly upload the gif to a Flarum forum with flagrow/upload on it, because again .. lazy ?
• Tag your first version, in case you want to be careful use a postfix like beta, eg 0.1.0-beta or if you expect multiple betas 0.1.0-beta.1 check the semver.org site for more. For stable use 0.1.0. Read up versioning in relation to composer if you postfix.
  • Tag using git tag 0.1.0 then push the tags using git push --tags.
• Go to discuss.flarum.org/t/extensions and create a thread. Copy over your readme.md (sorry guys .. lazy and it works for us ?). Post and favorite it so you get email alerts.

Continued work

Some stuff to consider after the initial release;

• It's better to use branches on git for new features.
• We ask for code reviews from our Flagrow fellow devs for new features. This is not only to guarantee better quality, but it also is a good way of learning new things.

So.. this is all from the top of my head. I most likely should link some things and might have left out (crucial) steps.

Feel free to ask for clarification or point out things I missed.

This is all based on my experience as team member of Flagrow, a project by Gravure.