springernature/frontend-playbook

The Frontend Playbook

The Frontend Playbook

This repo contains The Frontend Playbook. It details how we run software development and how we make web and mobile products together. It's filled with things we've learned based on our own experience and study of others' experiences.

The main motivator for this playbook is not to document a list of guidelines, but rather to create an opportunity to collaborate on them, and to gain consensus.

This is a living document that we contribute to in a public GitHub repo. Reasons for doing this in the open include (but are not limited to):

1. Interacting with and learning from others. Receiving contributions from people who don't work here can help us, providing learning opportunities that we would not receive otherwise - for example, see this contribution from @rowanmanning.

2. Providing a showcase for our work/ethics. This is really useful when hiring people (for both parties). We've had very positive feedback from interviewees - it's a great recruiting tool. It also means that people are quickly up and running when they join.

See "Changing the laws of engineering with pull requests" for an in depth explanation of how developing a playbook like this is of benefit.

Sections

There's no particular order to which you should read the playbook, but the Practices section is probably a good starting point.

• Accessibility
• CSS
• Git
• JavaScript
• Markup
• Performance
• Practices
• Security
• Writing

Contributing

To contribute please clone the repo (or fork it if you're an external contributor), create a new branch for your changes, then create a pull request to merge your changes in.

Please keep discussion inside the issues and pull requests, avoiding Slack, hallway conversations etc. Remember that this repo is public, and the discussions we have can be of benefit to people apart from us.

Read the full contributor guide.

Key words

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this playbook are to be interpreted as described in RFC 2119.

License

The Frontend Playbook is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

You should have received a copy of the license along with this work. If not, see Creative Commons BY-NC-SA 4.0 license.

frontend-playbook's Issues

Tried to contribute but cannot gain access rights

Detail general approach and advise re: use of "open in new window" links

This should touch on when it may and may not be appropriate to open links in new windows, as well as accessibility concerns.

Document our approach(es) to webfont loading

Summary of our discussion earlier today:

I think we were agreed on loading them with JS. There was discussion about non js users not getting the font, but that's ok I think. Even with the JS approach, there's differences between projects. We use session storage to set a flag once font has loaded, but link save the entire font as a data-uri in local storage (I think?)

we do save the entire font as a data-uri then retrieve it from local storage. I actually went through that article that was posted and tested out various options and we found this one to be the best for us. BUT it might not be best for all. We only have one webfont, and it has a limited character set so storing at as a data-uri works fine. not sure how well it would work with multiple fonts

the way we implement it is slightly different from how it is described in the article (https://www.zachleat.com/web/comprehensive-webfonts/#critical-foft-data-uri) as we don't write it inline

I actually think it is OK that we use slightly different methods, there is still a lot of common ground and we can probably write up a set of broader guidelines and then detail the individual approaches.

not like a document that decrees YOU MUST DO XYZ but more a document that outlines the problems, what we tried, and some recommended options

F-R-O-N-T-E-N-D

We seem to be somewhat inconsistent in the usage of frontend with/without a hyphen. We need to correct the ones that are wrong.

Simplify markup house style page

In the markup house style page there's a very long section explaining why we write HTML 5 (instead of XHTML). There are also several mentions of older versions of (X)HTML along the document, and how those old standards influence what we write today.

Although that whole page is beautifully written, it's 2018 and HTML 5 has been the standard for long enough that I'm concerned that many readers may not be familiar with XHTML or HTML 4 (or older!).

Is it necessary to explain why we use HTML 5? Could this page be improved by having a much much shorter and simpler explanation? I feel like it may feel less daunting to people getting started.

There's also a nicely written section about the HTML outline model. Considering this is directly related to accessibility and assistive technologies, should this section be included with the rest of the accessibility stuff (and adding links where necessary), instead of here?

Review the "Dependency management tools" section

We added a section about tools for managing Node.js dependencies to our Dependency management page.

Maybe it's not the best place to contain that information and we should have a separate page for tools.

strict mode

As mentioned by @hollsk in #48, need to add a bit to the JavaScript Style Guide about our usage of strict mode.

Add a code of conduct

The Contributor Covenant is used by over 40,000 open source projects (including Pa11y!)

http://contributor-covenant.org/

Namespacing node projects

Not namespacing stuff is a very bad practice in general. That that npm and most other tools have proper support for namespacing, we should aim to namespace every new project node-based project that we release (e.g. @springernature/potato instead of potato).

Recommendation to be added to the playbook.

Should we detail our current graded browser support levels here?

The information is currently published on the intranet so that people inside the business can see it. Now that the Playbook is open source, perhaps we should think about moving it here instead?

Tidy up (and add) "arrow functions" sections

We have this text for the "arrow functions" section. It's OK, but needs to use our "we do/we don't do" style. Therefore need to add a couple of extra examples (of what we don't do).

Arrow Functions

If the environment you're running in supports ES2015 (Node.js 4.x/Babel) then you can use arrow functions in place of anonymous JavaScript functions:

['FOO', 'BAR', 'BAZ'].map(string => string.toLowerCase());

Arrow function arguments do not need to be wrapped in brackets if there is only one.

Arrow functions can be on a single line if they don't require curly braces. For arrow functions with multiple statements, they must be multi-line:

doSomethingAsync((error, result) => {
    if (error) {
        return console.error(error);
    }
    console.log(result);
});

Arrow functions should not be used everywhere, only where otherwise an anonymous function would be used. You shouldn't replace your named functions with arrow functions:

var myFunction = (foo) => {
    console.log('Do not do this');
}

Add accessibility-related examples to Language guidelines

The language guidelines link to the Gov.uk website for disability-related examples.

Considering how important accessibility is for front end development, it would be better if we could add some examples to the document itself rather than rely on external sources.

Review browser support levels

Our usage statistics suggest that it is time to review the position of several browsers within our support policy. We should review the arguments for maintaining or reducing support for each browser.

Related: #107.

Accessibility - common concerns

A while ago, when we added the Accessibility guide, we discussed the need for a "Common concerns" section.

I've just realised we added the section but we left it empty. Any volunteers fancy tackling it, or shall we remove it?

Inline and reference hyperlinks

The README says:

If you need to reuse a hyperlink, turn it into a reference link. Otherwise, use an inline link.

But we're very inconsistent in the use of these, even in the README itself. I would suggest to either:

• Just use reference links everywhere, as it helps with legibility when you're reading the raw Markdown without a viewer, or
• Fix the links everywhere according our policy above

Guidelines on handling cookies on domains

At Nature.com -- particularly on subject pages, we are currently experiencing cookie overload.

Seems likely cause is the way cookies have been created, so falling back on browser's defaults.

Need to ensure that cookies only created if required, and there is no other way of handling any specific case.

If a cookie is created -- then proper headers are added: expiry dates, domain and url.

Document approach to form validation

Necessity of server-side validation
Use HTML5 validation, but don't attempt to shim into other browsers
Be cautious about js client-side validation

Linting

At the moment we mention stylelint in the CSS documentation. I added an example config file for this, but think that we also use SCSS lint, which I decided against using because of the Ruby dependency, and there is also SASS lint.

We also have Javascript linting in the nature playbook, should this be incorporated into the springernature one?

Is it wise to standardise around the same methods or do we just include details of all the methods used across teams? At the moment the section in CSS on 'the rules' only really matches the nature stuff and springerlink (because i nicked it).

Perhaps it would be better to have 'the rules' sitting within each language file, then a section on linting, which has methods for incorporating those rules?

Suggestion to make peer review FED process more inclusive

It might be sensible to make as small tweak to the wording on the PR playbook docs, on following line in Why section to make it more inclusive to wider dev community, as sometimes not just FEDs change templates and code; from, "Ensure that Front-End Developers within each team are coding to the same guidelines." To: "Ensure that any Developers, within each team, who are changing front-end templates or code are conforming to the same guidelines".

Please see: https://github.com/springernature/frontend-playbook/blob/master/practices/code-review.md

README.md

Add details to the readme about the purpose of this repo and instructions about how and when to create new issues.

Create effective colour contrast page

Recreate the "Effective colour contrast" page here, and link to it from guideline 3 in the accessibility checklist.

Add a table of contents / index

We've got a fair chunk of information but no real organisation, so it's a bit overwhelming when you open up the repo.

The house style page has transmogrified into a getting-started guide of sorts, but it doesn't include references to every file.

Propose we add an index that groups files into logical order, to give readers some idea of priority and structure. Maybe something like this:

• House Style
  • Accessibility
  • Accessibility checklist
    • Effective colour contrast
  • Code review
  • Graded browser support
• Markup
• CSS
  • OOCSS
  • BEM
  • Mosiac CSS
• JavaScript
• Node
  • Dependency managment
  • Semver
  • Tools

And so on (not a comprehensive list). Does this look like an ok idea?

What is the purpose of init functions when using modules?

It feels like unneccessary boilerplate.
https://github.com/springernature/frontend-playbook/blob/master/javascript/house-style.md#module-architecture

Template linting

It would be good to clarify somewhere that we enforce linting of templates using for example dustmite.

This helps us prevent issues like the ones mentioned in Snyk's blog, as our lint rules ban the if helper.

Should /languages be /technologies?

Seems a little confusing, especially as I want to create a "markup" page in there... also in my mind it clashes with the lovely new practices/language.md page which is about human languages.

Update a11y section

We need to update a11y pages because a) it's been a while b) changing legal landscape esp. in US.

"frontend" vs "front-end" is a continual source of confusion

We've decided it's "frontend" but nobody can remember, and there's contradictory references to "front end" and "front-end" all over the place.

Suggest we convert practices/commit-messages.md to practices/git.md and include the correct repo name convention in that file.

Add a "performance" section

I propose a "performance" section to contain the following existing files:

• advertising
• images
• graded browser support
• progressive enhancement

Is this idea awesome Y/N?

Train-Case

We seem to be using the expression train-case in three different places in our playbook, with the meaning "all lowercase, words separated by a hyphen".

Wikipedia seems to differ in the meaning of train-case:

If every word is capitalised, the style is known as Train-Case.

Proposing to change the name to one that is understandable to everyone, specially for non-native English speakers, without having to google it first. Any suggestions?

Defining dependency versions

It's probably a fairly minor point but I think it might be worth having a standard practice we use when defining dependency versions (for NPM-managed packages for example).

At the moment there are a range of ways that we specify versions - some are locked down to a particular release e.g. 1.2.3, others to ranges of releases. It could be useful to offer guidance on when it's preferably to use a range, and when it's better to lock to a specific version.

There are also several ways to define a range, which can cause confusion. See https://github.com/npm/node-semver#advanced-range-syntax for a whole heap of examples. I think we should aim to use the same range methods across the board (when they're equivalent and interchangeable).

JavaScript Code commenting

We need to create a document that details what level and style of commenting we require in our code. This relates to #27

Presentation: working with gemfury and private node modules

Add tone-of-voice guidelines to language section

Requested in #32 - practices/language.md is a more natural home for it than the contributor guidelines.

Detail the constraints that inform our work

We need a section of the playbook explaining what our constraints are, in order to answer questions such as "why do you appear resistant to frameworks?"

Topics we should cover, among others:

1. Accessibility.
2. The law (ADA, 2010 Equality Act, GDPR, whatever informs our work).
3. Our customers (amongst others, educational institutions with specific requirements relating to the above points).
4. Maintainability (we maintain sites over decades, meaning we place emphasis on web standards - that are expected to be relevant for much longer time spans than a specific framework).
5. Multiple product teams (as FEDs we need to share work across product teams, hence the need to crosscheck stuff with other FEDs - part of the reason for our use of PRs, and also informs our need to standardise on tooling/practices etc).

There are lots of techniques already detailed in the playbook. Now we just need to explain why we have chosen them.

As ever, do not feel overwhelmed by having to write the entirety of this in one go. E.g. if you're able to contribute only on the topic of accessibility, submit a PR with only that, and let someone else handle the rest.

Also there is no need to duplicate content - i.e. for accessibility there is no need to duplicate stuff already existing on our accessibility house style page, just link to it. All we need is stuff along the lines of:

Because of our need to develop accessible sites [link to relevant page], we regard as suspect any framework or tools that require extra or unusual work to make them accessible. For instance idiomatic code for some frameworks' allows or even suggests the use of non-semantic html. In this case we know that places a burden on us to train up every new developer to use this framework in a non-standard way, to avoid the use of non-semantic html.

Or something. It's Friday, I'm busy, I'm typing this in a rush and I've probably worded this horribly. You get the gist though?

: VS ::

Hi,

I see in your CSS documentation that you use ":" for your pseudo-elements (before, after) as for your pseudo selectors (hover, focus).

CSS 3 specifications say that pseudo-elements should be differenciated with two colons "::"
See this article from CSS Tricks.

Single colons are often used to support IE8 though. But the correct syntax is "::" for pseudo-elements.

Add something about using Jest

Best practices for images

We don't have any section mentioning what to do regarding images, I don't think, so it would be useful to add one mentioning our best practices, e.g.:

• When to use SVG, PNG, JPEG, also vector images vs bitmaps.
• How to optimise images that are going to be commited to a repo (e.g. imageoptim)
• How to optimise images that are going to be server from somewhere else (e.g. Immagine)
• Etc.

I was serious when I mentioned discussing "frontend" & "front-end"

I'm not convinced that there is a worthwhile reason for using two different formats to refer to things that are front-end related.

Pros and cons of using 2 different formats in particular circumstances:

Pros:

• erm

Cons:

• People have to stop and think about which one to use
• People have to stop and think about whether the one used in a PR is correct or not
• It's something that needs to be looked up

---

I don't really know how we got into this situation in the first place. Was it my fault? I hope it wasn't my fault.

Proposal:

Use "frontend" for everything. I'll update the Playbook. Nobody speaks or thinks about it ever again.

Pros:

• Everyone knows what to use
• It's still grammatically correct
• We will never need to speak of this or think about it ever again

Cons:

• People might not immediately find the content they're looking for if they search for "front-end" ¯_(ツ)_/¯

Separate general information into a general document

We have a few items that are general practices but that live in specific documents (e.g. the house style rationale section in technologies/javascript.md).

We should separate these out into more generally-applicable documents. Please could you all add areas to this ticket that you've identified as needing attention?

What's 'Mosaic'?

https://github.com/springernature/frontend-playbook/blob/master/practices/css/mosaic-css.md

This whole page is written under the assumption that you know what Mosaic is, which no one outside the company probably knows. We should describe it more accurately, so it can also be referenced properly from other documents.

Repo name

The repo is called frontend but the readme still says frontend-issues

Document our new approach to linting

Using https://github.com/springernature/eslint-config-springernature

JavaScript architecture

What we are doing

Contribution guidelines

Detail how we contribute to the playbook. PRs, tone of voice, etc.

See "Setting guidelines for repository contributors".

add "we do/don't do" links to "blocks" section

The blocks section in the JavaScript guidelines is missing the helpful "we do/don't do" code examples of other sections. Would be good to add.

Document our approach to cutting the mustard

Document approach to form submit buttons

There was recently a discussion on Slack wrt whether to use <input type="submit"> or <button> for form submit buttons. It was agreed in the end that we should use <button>.

See #frontend 26th Sept 1:54PM: https://springernature.slack.com/archives/C0GDUEGMS/p1506430489000133

Someone needs to formalise this in the playbook as an agreed approach including rationale.

Graded browser support table slightly out of date

From Jose in #108

This is the current list of C-Grade browsers in our legacy platform (which we've been using as a single source of truth so far):

Internet Explorer <9
Safari up to 4.0.x on Windows and OS X
Safari 2 (any) and Safari 3 (iPhone 1)
Unknown (User-Agent matches '.* AppleWebKit.Version/[0-2]..')
Safari 1
Unknown (User-Agent matches '.*Version/2.2 Firefox/525.13')
Firefox 0.x and 1
Opera up to 9.4
Nokia browser for Symbian 7.3
Android browser up to 2.x
Old versions of 'Mozilla compatible' browsers
Netscape

In bold the ones that don't match what's on the table. As you can see, there are others that are not on the table at all, I'm not sure what we want to do and if we want to put them there.

I don't think there's much value in adding things like Netscape or Moz compat browsers or anything weird and old to the documentation. They exist in the legacy platform because the legacy platform is also weird and old ;)

Let's update the C-grade column to use any higher values in Jose's comment.

Issues' labels

Github creates some labels by default, but those are arguably not very good in general, and in particular not very appropriate for a repo that is supposed to contain only issues.

There's a brilliant article about replacing the default labels with something saner, however it's oriented to projects that use issues as a replacement for a bug tracker, so it doesn't really apply to this repo I think:
https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63

Any ideas?

Presentation of what was presented at the Google "Progressive Web Apps" conference 17th March

Could someone please provide an overview of the conference and anything interesting that came out of it?