A good example is I just spent the last 30 minutes trying to figure it out how to have the user cards on my local. I went to success looking for a release note, found some client facing documentation, nothing technical.

Came here and found nothing...

Finally I looked directly for the code to find out some references that it might be behind a feature flag. (No readme though).

In my honest opinion, releasing a feature with no documentation is the same as the feature not existing at all.

Whenever I do some product related development I try documenting the feature I'm releasing in a readme or so. I'm not saying we should do exactly this but since we have been releasing a lot of feature flags recently I think it's becoming more pressing to have some sort of documentation protocol in place.

We brought this in because we wanted to be able to do type-hint like safety checks in old code. You usually want to call assertions as the first thing in a method. That way below them you know your data is correct and can proceed with cleaner code.

A little gotcha. There is a method called Assert::integer() which is not usually what you want to call. Instead call Assert::integerish() as an alternative that will work with string representations of integers. This is safer for old code and also data that comes from the database.

1. Most people don't know how our app ends up getting translated. I kind of just quietly order translations and put in the odd fix here and there and our translations just sort of magically happen.
2. Because of this black box process there are a few inefficiencies that cause me and other to end up having to do a lot of extra needless work.

To this end I decided to beef up our localization developer docs and I'm hoping you'll all give a read. I'm hoping that this article and articles like this can also help us onboard new developers better so if you don't understand something please leave a comment here or add a clarification directly to the article.

First, read the post I left to support. Then read the article on localization.

All devs should read and understand the article. My hope is for us to always strive towards a more streamlined development process, and handoffs between teams is often one of the biggest chokepoints. Understanding what other people have to do and what the repercussions of your work will really help with this.

What is static analysis?

Static analysis is an automated tool that is run on code that analyzes it for potential errors. It follows code paths to see if there are any easily identifiable errors in our code. What kinds of errors you may ask? There are too many to list, but here are some good ones.

• Calling functions with the wrong number of parameters.
• Using undeclared variables.
• Improper subclassing.
• Type mismatches

From detecting typos, to bugs that may take down a site, static analysis can help find things that humans often miss.

Why static analysis?

Static analysis is just another tool in our toolbox of code quality. It detects probable bugs. It helps keep our code clean and consistent. And the best part: we get this all essentially for free. We don't have to write specific tests for static analysis to work. It just runs in our code and tells us about problems.

What's the catch?

There isn't really much of a catch. However, there are a few strings attached with static analysis.

• Static analysis can report some false positives. This means it will tell us there is something wrong when we know there isn't. In these cases there are ways to address this (hint: read the docs). That being said: you may find addressing these issues a little tedious.
• We are not quite at the point where we have full code coverage with psalm. Turning on a tool like this on a mature code base always reports a tonne of errors. In our case this amounts to hundreds of errors. Not to worry though: I've dialed down the strictness of the tool to start in order to give us time to address some issues at least. I'll dial it up slowly over time as I am able to fix things. If you want to help with this then come talk to me.

What should I do to be ready?

In order to not get your knuckles wrapped by Psalm it’s best to code cleanly. Luckily code sniffer already detects a lot of what psalm needs to do its thing. Other than that I suggest the following:

• Read Psalm's docs! They explain the tool better than I can and are not too long of a read.
• Make sure you type hint as much as possible and make sure they are correct. Type hints allow for code analysis more than anything else. You can use @param hints or real type hints. Psalm will use both.
• For new functions avoid multiple allowed types for parameters. This is manifested a lot in our codebase where we take an array parameter or result, but default it to false. This is a bad habit that we should avoid going forward.
• Pay attention to PHPStorm's inspections. PHPStorm already does a measure of static analysis. If you fix its errors then you are one step closer to a clean bill of health from Psalm.

Anyway, you will start seeing Psalm as part of our build process. You can also run it locally from your vanilla directory with:

./vendor/bin/psalm

Happy coding!

There's been a lot of person to person discussion about this over the last year, but I'm finally getting the ball rolling on it.

Whats's changing?

The internal, multisite, knowledge, and analytics repos will be retired. In the future the addons repo may be considered as well.

All cloud plugins that were previously in these repositories will now live in a new private repository vanilla-cloud along with the codebase of the existing vanilla/vanilla repo.

The repository is still being configured but you can find it here. vanilla/vanilla-cloud

New Structure

• A direct fork of vanilla/vanilla.
• All cloud addons now reside in either the /cloud/plugins, /cloud/themes, or /cloud/applications directories.
• vanilla-patches will go away. Instead PRs can be made directly to vanilla-cloud.

Why now?

The long and short of this is that as our product gets more integrated (larger more fully featured addons instead of small 1-2 week projects), maintaining them has become far more complicated. Often times a single feature can require multiple PRs across multiple repos with a complex chain of dependencies. This can make review, CI, and locally checking out changes a lot more complicated.

More detailed reasons can be found in this article.

What about my PRs?

It is possible to synchronize code back and forth between the old repos and the new repo, although a bit tedious.

Guides are available for switching your localhost to use the new repository.

There are also guides for moving existing PRs.

Timeline of Changes

The timeline of changes is planned as follows.

Fri Jun 26 - Release 2020.013 will be branched from the old repositories. This will be the last cloud release to use these repositories.

Mon Jun 29 - Team supreme will begin using the new vanilla-cloud repository.

During this time other teams may continue to make PRs against existing repositories.

Friday July 5 - I will sync any changes from master branch in the old repositories to the new one.

Mon July 6 - Other teams should being using the new vanilla-cloud repository.

Fri July 11 - Release 2020.014 is branched from the new repository. I will provide a script to adjust infrastructure for the new structure and assistance will be given during the staging deploy.

For those not in the know, we currently support PHP right up until that version is no longer supported itself. This is for some good reason. Most servers don't update major software every year. There needs to be a buffer of support. Our operations team is on a two year cycle, for example.

This also means that we are currently on PHP 7.2. That's two versions behind current PHP. It will be three years passed release by the time we sunset support. That's a lot of time. With that wait we miss out on incremental improvements to our productivity and software quality that are essentially "free" to us.

What I think we should do this year is jump to PHP 7.4 support rather than moving to PHP 7.3. That will be the same amount of effort for ops since they are upgrading to PHP 7.4 anyway.

After that, we wouldn't be upgrading to PHP 8.0 in its release year and are likely again to jump to PHP 8.1 the following year instead. So two versions every two years instead of one version every year. Not super different.

If you want to enable it for our javascript dependencies, you can make a PR to the config file @Adam Charron. I recommend doing a manual update first though.

The idea is to make all classes available in unit tests, regardless of whether or not addons are enabled.

My reasoning for this is that I think it will make writing addon unit tests easier. You can write your tests and know that all of your classes are there. Ideally, we write more unit tests than other tests and usually those don't need an extra installation of Vanilla. I see some tests manually requiring files; this change would make that unnecessary.

On the downside, this could lead to scenarios where tests pass, but production fails because of specific autoloading issues. This is something we'll have to decide on whether or not the benefits outweigh the side effects.

Another thing I encountered when making this change is problems with duplicate classes. If you look at my PR, I specifically exclude some plugins that caused this problem. These issues stemmed from two places:

1. Plugins that have their own composer.json that include a duplicate vendor directory. In this case, we have changes in the works to bring these composer dependencies into the main vendor directory. If/when we make that change then this problem will go away.
2. Some plugins just define duplicate classes. To me, this is a bad practice that we should work to avoid. Having this global autoloader will help us avoid this issue in the future as tests will now fail if we define duplicate classes. As we move towards everything being in a namespace then this type of issue should go away.

Anyway, let me know if you have any specific questions or objections about this proposal. You can react to this post, comment below, or even review the PR.

I find that often we add a lot of things that people aren't aware of and I would like that to change. I want our platform to be one that is continuously improving which means there will be "old" ways to do certain things, and "new" ways to do those things.

Here are some examples of things I would like to see in this category:

• Announcements of new composer packages that have been brought into core. Generally, we like to use mature libraries that have already been written, rather than write our own.
• New ways to help write unit tests more easily. Usually, when I write a new unit test I will often add a new trait or utility method somewhere that will help others.
• Requests for comment on new ideas for core. If you have an idea post it here. Let me ask though that you give ideas that are specific and actionable. Changes that involve us changing code across every repo are not likely to get done, while making small incremental improvements are better.
• Deprecation announcement and discussion. We deprecate code from time to time. When you do deprecate something, try and announce it here. More importantly, tell the developers the new way to do things. We should never deprecate without another way of doing things.

Try and avoid lengthy documentation here as that is better suited for the knowledge base. However, if you do write a new piece of documentation, consider writing a discussion and linking out to it.