How to contribute

Before diving into code it might be worth reading through the Developing on Bedrock documentation, which contains useful information and links to our coding guidelines for Python, Django, JavaScript and CSS.

Git workflow

When you want to start contributing, you should create a branch from main. This allows you to work on different project at the same time:

$ git switch main

$ git switch -c topic-branch

To keep your branch up-to-date, assuming the mozilla repository is the remote called mozilla:

$ git switch main

$ git pull --ff-only

More on Why you should use –ff-only. To make this the default update your Git config as described in the article.

$ git switch topic-branch

$ git rebase main

If you need more Git expertise, a good resource is the Git book.

Once you’re done with your changes, you’ll need to describe those changes in the commit message.

Git commit messages

Commit messages are important when you need to understand why something was done.

  • First, learn how to write good git commit messages.

  • All commit messages must include a bug number. You can put the bug number on any line, not only the first one.

  • If you use the syntax bug xxx, Github will reference the commit into Bugzilla. With fix bug xxx, it will even close the bug once it goes into main.

If you’re asked to change your commit message, you can use these commands:

$ git commit --amend

-f is doing a force push because you modified the history

$ git push -f my-remote topic-branch

Submitting your work

In general, you should submit your work with a pull request to main. If you are working with other people or you want to put your work on a demo server, then you should be working on a common topic branch.

Once your code has been positively reviewed, it will be deployed shortly after. So if you want feedback on your code but it’s not ready to be deployed, you should note it in the pull request, or use a Draft PR. Also make use of an appropriate label, such as Do Not Merge.

Squashing your commits

Should your pull request contain more than one commit, sometimes we may ask you to squash them into a single commit before merging. You can do this with git rebase.

As an example, let’s say your pull request contains two commits. To squash them into a single commit, you can follow these instructions:

$ git rebase -i HEAD~2

You will then get an editor with your two commits listed. Change the second commit from pick to fixup, then save and close. You should then be able to verify that you only have one commit now with git log.

To push to GitHub again, because you “altered the history” of the repo by merging the two commits into one, you’ll have to git push -f instead of just git push.

Deploying your code

These are the websites that Bedrock is usually deployed to as part of development.

Demo sites

Bedrock as a platform can run in two modes: Mozorg Mode (for content that will appear on mozilla.org) and Pocket Mode (for content that will end up on getpocket.com).

To support this, we have two separate sets of URLs we use for demos. To get code up to one of those URLs, push it to the specified branch on github.com/mozilla/bedrock:

For example, for Mozorg:

$ git push -f mozilla my-demo-branch:mozorg-demo-2

Or for Pocket:

$ git push -f mozilla my-demo-branch:pocket-demo-1

Deployment notification and logs

At the moment, there is no way to view logs for the deployment unless you have access to Google Cloud Platform.

If you do have access, the Cloud Build dashboard shows the latest builds, and Cloud Run will link off to the relevant logs.

There are Mozilla Slack notifications in #www-notify that show the status of demo builds. (Work is ticketed to make those notifications richer in data.)

Env vars

Rather than tweak env vars via a web UI, they are set in config files. Both Mozorg and Pocket mode have specific demo-use-only env var files, which are only used by our GCP demo setup. They are:

  • bedrock/gcp/bedrock-demos/cloudrun/mozorg-demo.env.yaml

  • bedrock/gcp/bedrock-demos/cloudrun/pocket-demo.env.yaml

If you need to set/add/remove an env var, you can edit the relevant file on your feature branch, commit it and push it along with the rest of the code, as above. There is a small risk of clashes, but these can be best avoided if you keep up to date with bedrock/main and can be resolved easily.

Secret values

Remember that the env vars files are public because they are in the Bedrock codebase, so sensitive values should not be added there, even temporarily.

If you need to add a secret value, this currently needs to be added at the GCP level by someone with appropriate permissions to edit and apply the Terraform configuration, and to edit the trigger YAML spec to pass through the new secret. Currently Web-SRE and the backend team have appropriate GCP access and adding a secret is relatively quick. (We can make this easier in the future if there’s sufficient need, of course.)

Note

Always-on vs auto-sleep demo servers

The demo servers are on GCP Cloud Run, and by default they will be turned off if there is no traffic for 15 minutes. After this time, the demo app will be woken up if it receives a request.

Normally, a ‘cold start’ will not be a problem. However, if the branch you are demoing does things that alter the database (i.e contains migrations), then you may find the restarted demo app crashes because the new migrations have not been applied after a cold start.

The best current way to avoid that happening is:

  • In your branch’s demo-env-vars YAML file, set LOCAL_DB_UPDATE=True so that the Dev DB is not pulled down to the demo app

  • Ask one of the backend team to set the Demo app to always be awake by setting ‘Minimum instances’ to 1 for the relevant Cloud Run service and restarting it. The app will always be on and will not sleep, so won’t need a cold start. Once you have completed the feature work, please ask the backenders to restore the default sleepy behaviour. As an example with mozorg-demo-1:

    • To make it always-on: gcloud run services update mozorg-demo-1 --min-instances 1

    • To revert it to auto-sleeping: gcloud run services update mozorg-demo-1 --min-instances 0

(We’ll try to make this a self-serve thing as soon as we can).

DEPRECATED: Heroku Demo Servers

Demos are now powered by Google Cloud Platform (GCP), and no longer by Heroku.

However, the Github Action we used to push code to Heroku may still be enabled. Pushing a branch to one of the demo/* branches of the mozilla/bedrock repo will trigger this. However, note that URLs that historically used to point to Heroku will be pointed to the new GCP demos services instead, so you will have to look at Heroku’s web UI to see what the URL of the relevant Heroku app is.

To push to launch a demo on Heroku:

$ git push -f mozilla my-demo-branch:demo/1

Dev

Staging

  • URL: http://www.allizom.org/

  • Bedrock locales: prod repo

  • Bedrock Git branch: prod, deployed on git push with date-tag

Production

  • URL: http://www.mozilla.org/

  • Bedrock locales: prod repo

  • Bedrock Git branch: prod, deployed on git push with date-tag

You can check the currently deployed git commit by checking https://www.mozilla.org/revision.txt.

Pushing to production

We’re doing pushes as soon as new work is ready to go out.

After doing a push, those who are responsible for implementing changes need to update the bugs that have been pushed with a quick message stating that the code was deployed.

If you’d like to see the commits that will be deployed before the push run the following command:

$ ./bin/open-compare.py

This will discover the currently deployed git hash, and open a compare URL at github to the latest main. Look at open-compare.py -h for more options.

We automate pushing to production via tagged commits (see Push to prod branch (tagged))