This article is for Enterprise customers who have a self-development agreement with Vanilla Cloud.
This article contains information regarding branch naming and pull requests so that your self-developed addons can be deployed to your site on Vanilla's cloud infrastructure.
Localhost development
You should do your self development against an instance of Vanilla running locally. It's important to do debugging and testing locally so that you can submit a pull request once and have it approved.
To learn how to set up Vanilla on your localhost, see localhost installation instructions.
GitHub repository
If you're developing addons for Vanilla, you'll be given access to a GitHub repository named after your company on the vanillaforums organization. This is where all of your code will live.
You can request your individual developers be given write access so that they can make pull requests on this repository.
Branches and deployment
On Vanilla cloud, we will deploy fixed branches on your repository to your various sites. The branches should be named as follows:
- The develop branch will be deployed to your development site.
- The stage branch will be deployed to your staging site.
- The master branch will be deployed to your production site.
📝 NOTE: Customers without a development site will not need a develop branch.
📝 NOTE: If you contact Vanilla Support, the "master" branch will be referred to as the "production" branch.
Branch-protection rules
We typically put the following branch-protection rules on the stage and master branches.
- Changes to the branch require a pull request.
- Pull requests require at least one approval from Vanilla staff.
Pull requests
You must do all of your development via pull requests against the branch you want to deploy to. Except for develop branches, all pull requests must be approved by Vanilla staff. This is for two reasons:
- to ensure that unsafe or insecure code does not get deployed to our infrastructure,
- and so we have an opportunity to check for best practices.
In general, branches that require pull requests will have branch-protection rules against them to prevent you from pushing code to them without a review. You're free to create other branches for pull requests and name them whatever you wish.
When you're ready to have a pull request reviewed, create a support ticket by emailing support@vanillaforums.com so that your review can be expedited by a support agent. When requesting a review, you should also specify what you want done:
- Review Only: Just review the pull request and approve it. Once the pull request is approved, you can then merge it yourself.
- Merge: Review the pull request and merge it.
- Deploy: Review the pull request, merge it, and then deploy it to the appropriate cluster.
📝 NOTE: In the email, be sure to share the pull-request number and which branch it is.
Making pull requests to stage and production
Generally, you want to do all of your development against your develop branch (or your stage branch if you don't have a develop branch). You want to get your development site into a tested state where you will then be confident having your code deployed to staging and then production.
Merging to stage
When you want to merge to stage, make a pull request to merge from develop to stage. Don't create a new branch name just for merging code to stage.
Merging to master
When you want to merge to master, make a pull request to merge from stage to production. Don't create a new branch name just for merging code to master.
Using consistent branch names like this allows Vanilla staff to know whether they have already reviewed your code, and can help to expedite your pull-request review. If you create new branch names, it's difficult to determine whether you have written new code or whether you are just wanting to merge already tested code into production.
Keep your environments in sync
You should not have your various environments differ from each other. Your staging and development environments are meant to represent work in progress. Once that work is done, it should be merged to production in its entirety.
If you need slightly different configurations or settings between environments, use Vanilla's configuration functionality to represent these differences. Don't store configuration in your code that may differ from one environment to another.
Vanilla's pull request review process
Vanilla's engineers must review your pull requests before they can be merged and deployed. This review process is not as exhaustive as an internal pull request review process may be within your own company. What we are looking for are potential scalability or security issues that could negatively affect our infrastructure and your site.
Here are some guidelines you can follow to ensure your pull requests get approved without issue:
- Avoid excessive calls to the database. You generally want to have a decent understanding of database performance if you need to query the database in your code.
- Avoid writing hard-coded SQL statements in your code; use Vanilla's model methods instead.
- Never make a call to the database within a loop. Also, pay attention to the number of database calls you make in a request.
- Don't make API calls on the server during GET requests. Be careful about API calls in general (they are costly).
- Be conscious of permission checks when you add new endpoints.
- We generally don't look too closely at frontend files, such as CSS or JavaScript.
- We generally don't look too closely at Twig templates.
- Try to write as much of your code in frontend files as possible, using Vanilla's existing APIv2.
- It is your responsibility to ensure your own code is tested, and to fix issues that may arise in production. For this reason, write as little code as possible to achieve your goal.