The Pivotal Engineering Journal
Welcome to our little slice of the internets! This blog is dedicated to technical (and cultural) posts by the Pivotal Engineering team. If that's you, then please, please, please contribute!
This blog is built and maintained entirely by you! Feel free to propose or just implement any improvement you believe in. ANARCHY!!!!
- Write your post as a draft.
- Preview it on staging.
- Make it good. Gather feedback from your engineering peers. Iterate, repeat.
- Ship it!
If you don't have push access, then send an ask ticket to have yourself added to the
all-pivots github team in this org.
Writing a Post
It's a good idea to join the Slack channel, if only to get notifications on build failures, etc. It's also a good place to discuss article topics.
Add yourself as an author (first time only, obvs.):
$ cp data/authors/tammer.yml data/authors/bob.yml $ vi data/authors/bob.yml
Create a new draft post:
This creates a new file at location
markdown, and the template provides instructions on any advanced bits. Be sure
to change the metadata in the file's YAML front-matter — one thing to
change immediately is the
authors: value; it should include the name of your
author file (
bob in the example above) in the list.
- Meta: If you want to change the default new post template, it's in
Writing a Good Post
Pair all the time. We do everything as a team, and this is no different. Get feedback from your friends and coworkers. Show them the post on the staging site, and ask them to tear it apart.
Keep it technical. People want to to be educated and enlightened. Our audience are engineers, so the way to reach them is through code. The more code samples, the better.
Nobody likes a wall of text. Use headers to break up your text. Each image you add to your post increases its XP by 100. Diagrams, screen shots, or humorous "meme" (|memā|) gifs... They all add color. If you don't have OmniGraffle, then submit an ask ticket. There's no excuse for monotony.
Your 10th grade teacher was right. Make use of the hamburger technique. Your audience doesn't have a lot of time. Tell them what you're going to write, write it, and then tell them what you've written. Spend time on your opening. Make it click.
Make it pretty. Pivotal-ui comes with a bunch of nice helpers. Make use of them. Check out the example styles in the default post template.
Post formatting gotchas
Currently, if you have links or line breaks in your
short: description it will not format correctly.
This site uses Hugo v0.60.1, which is easy to install:
$ brew install hugo $ hugo version Hugo Static Site Generator v0.60.1/extended darwin/amd64 BuildDate: unknown
After cloning this repository, navigate into the new directory, run
bin/watch in a terminal and then browse to http://localhost:1313 to see your local copy of the blog.
Hugo has LiveReload built in, so if you have that configured in your browser, your window will update as soon as you make a change. Hugo is fast, so you might not realize the reload has already happened.
Viewing on Staging
You can also double check your work by looking on the staging site. Every PR deployed to a path that matches its number (ex.
/254). Draft posts are only published there.
If you get an error like:
Error while rendering page foo: reflect: call of reflect.Value.Interface on zero Value
Then you may have forgotten to include a property in your
Publishing Your Copy
Every commit to master is auto-deployed to both production and staging (only staging shows drafts). If you don't have push access, then send an ask ticket to have yourself added to
all-pivots in this org. To publish your draft post, simply remove the
draft: true line from the top of your post.
Changing the style
All of the HTML and CSS live in
themes/pivotal-ui, which is a port of the Pivotal UI project. I basically copied the compiled css and image files over. If you want to change the look of this site, then you should edit the templates in there.
The key files you'll want to look at are:
themes/pivotal-ui/layouts/index.htmlfor the main page...
themes/pivotal-ui/layouts/_default/single.htmlfor the layout around each blog post...
themes/pivotal-ui/static/local.cssfor CSS changes...
- ...and basically everything else under
Highlight.js is included for syntax highlighting. Any markdown producing
code pre tags will be highlighted by default, which means anything like:
~~~ruby instance = Class.new("foo") ~~~
If the language auto-detection fails you can add a language identifier. To disable syntax highlighting specify
no-highlight as the language identifier.
Under the Hood...
You'll notice that we're not building directly into
public, but rather into all of
public/staging — each representing a different environment. This magic is done by the bin/build script.
cf push will push all of the apps one at a time.
We also use:
- Feedburner to track RSS subscriptions, based on feed xml generated by Hugo
- A twitter account (automatically publishes each post via feedburner).
- Keen.io to collect metrics
- Segment.com for annotating and sending them to Keen.io.
- PushPop for sending metrics emails.
- And, of course, Pivotal Web Services for hosting ;)
All passwords are stored in Lastpass, available to the CF Engineering Directors, under the "Shared-Blog" folder.