`), and an example of inappropriate use of semantic elements (for example, using an `
` followed by an ``.
21 |
22 | ## Validate HTML
23 | ... demonstrate use of W3C Markup Validation Service to confirm the validity of markup for a webpage.
24 |
25 | ## Page structure
26 | ... explain the main components of a page (for example, `Header`, `Navigation`, `Main`, `Sidebar`, `Footer`), along with a use case.
27 |
28 |
29 | ## Specificity
30 | ... identify how css weighs selectors for displaying the most relevant style.
31 |
32 | *Resources:*
33 | * [How To Apply CSS Styles to HTML with Cascade and Specificity](https://www.digitalocean.com/community/tutorials/how-to-apply-css-styles-to-html-with-cascade-and-specificity)
34 |
35 | ## The Cascade
36 | ... differentiate between css properties that trickle down from parent to child selectors (`color`, `font-size`), and properties that don’t necessarily move down the cascade (`margin`, `padding`). They can also give an example of a CSS conflict and how it relates to the cascade.
37 |
38 | ## Navigate browser developer tools
39 | ... open the dev tools, inspect elements, and use the console.
40 |
41 | ## Basic Sass things: Variables, functions, mixins
42 | ... describe Sass variables, functions, and mixins, as well as why and when they should be used.
43 |
44 | ## Naming components: BEM & ITCSS
45 | ... describe BEM and ITCSS. They can explain how BEM prep HTML to be styled and how ITCSS creates a framework to structure our CSS.
46 |
47 | ## Breakpoints & MediaQueries
48 | ... identify how media queries can be uzed to provide layout on multiple screen sizes in a squishy web.
49 |
50 | ## CSS Layout
51 | ... understand different layout strategies for different levels of browser support.
52 |
53 | ## Box Model
54 | ... describe the box model properties of border, margin, padding, and how those properties relate to the content and the layout of elements on a web page.
55 |
56 | ## Document flow
57 | ... describe how elements are arranged.
58 |
59 |
60 | [career growth]: https://www.figma.com/proto/0FdKsjKvwf2H6KQpgRvT9Q/Sparkbox-Developer-Career-Growth-Framework?scaling=scale-down-width&hide-ui=1
61 | [gs cheat sheet]: https://codepen.io/team/sparkbox/pen/rjJJNQ
62 |
--------------------------------------------------------------------------------
/security/security_policy_compliance/two-factor-authentication.md:
--------------------------------------------------------------------------------
1 | # Two-factor Authentication
2 | In this guide you'll learn in principle how to setup two-factor authentication (2FA) for services which support it, along with an example. This is not intended to be a comprehensive guide to setting up two-factor authentication everywhere Sparkbox requires it.
3 |
4 | ## An Overview of 2FA
5 | Two-factor authentication refers to the number of pieces of information required to sign in to a service. Most people will be familiar with signing in to Facebook or their bank with a password but some services go further than passwords, requiring an additional piece of information to prove you are who you claim to be. That's the second factor, the first being your password. It often comes in the form of a 6-digit number called a "token" and is tied in some way to the specific service asking for it. You will setup separate 2FA for each service.
6 |
7 | ## Methods
8 |
9 | ### SMS
10 |
11 | __[Obtaining auth tokens via SMS is discouraged][nist-out-of-band-verifiers] and should only be used if the service offers no alternatives.__
12 |
13 | SMS-based 2FA uses your mobile phone to receive text messages from the service in question. Their systems will generate a token and send it to your phone, you then type into your web browser. Tokens generated via this method are usually only valid for a few minutes. Setup is dependent on the service and it will always require your mobile phone number (obviously). An initial SMS message will have instructions for verifying that your setup is successful.
14 |
15 | ### Authenticator App
16 |
17 | Apps are available for most mobile phone platforms to generate tokens. The two we rely on the most are:
18 |
19 | * Google Authenticator [Android][ga-play-store] [iOS][ga-app-store]
20 | * [Authy][authy-website]
21 |
22 | These apps work by having you scan a QR code with your phone's camera. Once scanned, your screen will show a number and a countdown timer. The number is the token and the timer indicates when the token will expire. The service for which you are enabling 2FA may ask you to verify setup by entering the code being displayed.
23 |
24 | ### 1Password
25 |
26 | In addition to creating and storing strong passwords for you, 1Password can also act as a token generator for 2FA.
27 |
28 | To setup an existing account for 2FA, open find the login in 1Password and open it for editing. Add a new field and choose `One-Time Password` from the field type selector.
29 |
30 | 
31 |
32 | An icon resembling a QR code will appear at the right of the field. Clicking that icon will open this window.
33 |
34 | 
35 |
36 | That window will always stay on top of other windows. Click and drag it on top of the QR code and 1Password will detect it automatically.
37 |
38 | [nist-out-of-band-verifiers]: https://github.com/usnistgov/800-63-3/blob/033fac493fd132cd6281b58ea7e430c0c222e40c/sp800-63b/sec5_authenticators.md#5132-out-of-band-verifiers
39 | [authy-website]: https://www.authy.com/
40 | [ga-play-store]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
41 | [ga-app-store]: https://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8
42 |
--------------------------------------------------------------------------------
/code-style/git/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | ### Description
2 |
3 |
4 | ### Spec
5 |
6 | Designs: [Designs](DESIGN_URL)
7 |
8 | See Story: [ISSUE_NUMBER](ISSUE_URL)
9 |
10 | ### Validation
11 |
12 |
13 | * [ ] This PR has visual elements, so it was reviewed by a designer.
14 | * [ ] This PR has code changes, and our linters still pass.
15 | * [ ] This PR affects production code, so it was browser tested (see below).
16 | * [ ] This PR has new code, so new tests were added or updated, and they pass.
17 | * [ ] This PR has new SCSS functions, mixins, or variables, so [Sass Tests](https://sparkbox.com/foundry/how_and_why_we_unit_test_our_sass) were added or updated, and they pass.
18 | * [ ] This PR has copy changes, so copy was proofread and approved.
19 | * [ ] The content of this PR requires documentation, so we added a detailed description of the component's purpose, requirements, quirks, and instructions for use by designers and developers. Along with accessibility information if pertinent.
20 |
21 | #### To Validate
22 |
23 | 1. Make sure all PR Checks have passed (GitHub Actions, CircleCI, Code Climate, Snyk, etc).
24 | 2. Pull down all related branches.
25 | 3. Confirm all tests pass.
26 |
27 |
28 |
31 |
32 | ---
33 |
34 | #### Browser Testing
35 |
39 |
40 | #### Gold Level Support
41 |
42 | In these browsers, behavior & design closely match original specifications. A user is able to access all content and functionality, including the usability of required assistive devices, such as keyboard and screenreader.
43 |
44 | **macOS**
45 |
46 | * [ ] Safari (last 2 major versions)
47 | * [ ] Chrome (last 6 months)
48 | * [ ] Firefox (last 6 months)
49 |
50 | **Windows**
51 |
52 | * [ ] IE 11
53 | * [ ] Chrome (last 6 months)
54 | * [ ] Firefox (last 6 months)
55 | * [ ] Edge 18
56 |
57 | **Mobile**
58 |
59 | * [ ] Safari (last 2 major versions)
60 | * [ ] Android 7+
61 | * [ ] Samsung Browser (last year)
62 | * [ ] Chrome (last 6 months)
63 | * [ ] Firefox (last 6 months)
64 |
65 | #### Silver Level Support
66 |
67 | In these browsers, behavior & design are acceptable, but may not be as originally intended. A user is still able to access all content and functionality as described.
68 |
69 | * [ ] IE 10 on Windows
70 | * [ ] Android 6+
71 | * [ ] Safari 7+
72 | * [ ] Edge 16
73 | * [ ] Samsung Browser (last 3 years)
74 |
75 | #### Bronze Level Support
76 |
77 | In these browsers, behavior & design may not be great, but the content doesn't appear "broken" to the user, either. All content is accessible, and functionality is as described. Additional testing may be required during implementation.
78 |
79 | * [ ] IE 9 on Windows
80 | * [ ] Android 5+
81 | * [ ] Safari 6+
82 |
83 | ---
84 |
85 | ### Changelog
86 |
89 |
90 | #### Features ✨
91 |
92 | * [ ] [Add _____](link to commit/pr)
93 |
94 | #### Fixes 🚧
95 |
96 | * [ ] [Fix _____](link to commit/pr)
97 |
--------------------------------------------------------------------------------
/software/ssh/README.md:
--------------------------------------------------------------------------------
1 | ## SSH
2 |
3 | We authenticate with remote servers using [PKI][pki], which means we use generated keys stored in files on our computers rather than passwords that must be typed each time we connect. The first step is to generate these keys using the `ssh-keygen` command:
4 |
5 | $ ssh-keygen -t rsa -b 4096
6 |
7 | This will ask you a few questions. The first two deal with how to name the files and where to store them. Unless you have a really good reason, use the defaults as they work well with a majority of use cases. If it asks you if you want to overwrite an existing file, stop and get help. It'll next ask you for a passphrase. Leaving the password blank reduces the security nominally, but increases convenience significantly. Unless your org has requirements about having passwords on keys, it’s usually ok to leave this blank. (It'll also ask you to confirm the passphrase, which can be blank as well). This will leave you with two files:
8 |
9 | - id_rsa
10 | - id_rsa.pub
11 |
12 | After you have your keys, clone the [public keys repository][public_keys] repository and add or replace your key. Give it a short but descriptive name to differentiate it from the others.
13 |
14 | $ cp ~/.ssh/id_rsa.pub myockey.pub
15 | $ git add myockey.pub
16 | $ git commit -m "chore: Adding Yock's public key"
17 | $ git push
18 |
19 | You should only ever put the `id_rsa.pub` key into this repository and never share `id_rsa`. We use a tool called [Forte][forte] to distribute these keys to our servers. Work with [Ryan][ryan] or [Adam][adam] to get this done.
20 |
21 | The shared account username is in the Sparkbox 1Password vault. See the server entry for Sparkbox QA.
22 |
23 | ## Using an SSH config file / Creating Identity Files
24 |
25 | By creating a local configuration file for SSH, you can create shortcuts for servers you frequently access and define more advanced options. Additionally, by creating identity files, you can revoke or update a key for a specific server without having to edit the key everywhere else.
26 |
27 | If you haven’t done so yet, create a config file:
28 |
29 | $ touch ~/.ssh/config
30 |
31 | To add a host, add the required parameters you’d need to SSH into the server, like `User`, `HostName`, and optionally `IdentityFile`.
32 |
33 | Host example_server
34 | User sparkler
35 | HostName 23.222.222.2
36 | IdentityFile ~/.ssh/example/id_rsa
37 |
38 | The `IdentityFile` option above is simply another generated private key, just like our `~/.ssh/id_rsa` key. To generate this key in this example, we would have run the following command:
39 |
40 | $ ssh-keygen -f ~/example/id_rsa -t rsa -b 4096
41 |
42 | The `-f` flag specifies the file location. For help with other options, visit this resource on [generating a new SSH key][keygen].
43 |
44 | After saving, you can open a new SSH session to this server by running this command:
45 |
46 | $ ssh example_server
47 |
48 | You can append as many hosts as you need to your config file.
49 |
50 | ## Debugging SSH
51 |
52 | Sometimes we run into issues trying to SSH into a server. Do we have the wrong username? Did we incorrectly store our HostName? Running SSH commands in verbose mode can help us debug our ssh connection.
53 |
54 | Verbose mode causes ssh to print debugging messages about its progress. It is run by adding the `-v` flag. Multiple v’s increase the verbosity of the messages (with a maximum of three) e.g. `-v` vs `-vvv`. Additionally, you can create a log file (instead of a standard error) with the `-E` flag followed by the name of the file you want to save. So an example of a verbose ssh connection with errors logged would be this:
55 |
56 | $ ssh example_server -vvv -E log_file
57 |
58 | Run `man ssh` for additional parameters you can run with ssh.
59 |
60 | [keygen]:https://www.ssh.com/ssh/keygen/
61 | [adam]:https://sparkbox.slack.com/messages/@adam/
62 | [ryan]:https://sparkbox.slack.com/messages/@cromwell/
63 | [public_keys]: https://github.com/sparkbox/public_keys
64 | [forte]: https://github.com/yock/forte
65 | [pki]: http://www.techrepublic.com/article/a-beginners-guide-to-public-key-infrastructure/
--------------------------------------------------------------------------------
/security/security_policy_compliance/devices.md:
--------------------------------------------------------------------------------
1 | # Device Security
2 |
3 | ## iOS Passcode
4 | As of iOS 9, Apple has increased Passcodes from 4 numbers to 6. Along with
5 | other improvements, this has a dramatic effect on the ability to [brute
6 | force](http://fortune.com/2016/03/18/apple-fbi-iphone-passcode-hack/) access.
7 |
8 | ### Setting a Numeric Passcode
9 | A numeric passcode can be set by:
10 |
11 | 1. Settings -> Touch ID/Face ID & Passcode (Note: Touch ID is only available on 5s and
12 | newer; Face ID is available on the X or newer)
13 | 2. Turn Passcode On
14 | 3. Enter a 6 digit number
15 |
16 | ### Setting an Alphanumeric Passcode
17 | Passcodes are more complex the more components they can contain. iOS does
18 | support an alphanumeric passcode by:
19 |
20 | 1. Settings -> Touch ID/Face ID & Passcode
21 | 2. Turn Passcode On
22 | 3. Select _Passcode Options_ in blue #0000ff
23 | 4. Choose Custom Alphanumeric Code
24 | 5. Enter a passcode 6 or more entries in length
25 |
26 | ### Touch ID
27 | With iPhone 5s and greater, Apple has implemented Touch ID. Once a 6 or greater
28 | passcode has been set, Touch ID is absolutely acceptable.
29 |
30 | ### Face ID
31 | With iPhone X and greater, Apple has implemented Face ID. Once a 6 or greater
32 | passcode has been set, Face ID is absolutely acceptable.
33 |
34 | ### Setting Passcode Activation Period
35 | Passcode activation period is the time after which an idle iPhone or iPad will
36 | require a passcode. This can be set by:
37 |
38 | 1. Settings -> Touch ID/Face ID & Passcode
39 | 2. Require Passcode
40 | 3. Choose a time of _After 5 minutes_ or less.
41 |
42 | Enabling _Use Touch ID/Face ID for iPhone Unlock_ and _Use Touch ID/Face ID for iTunes & App
43 | Store_ within Settings -> Touch ID & Passcode results in a _Required Passcode_
44 | of _Immediately_. This is great!
45 |
46 | ### Capturing Status
47 |
48 | 1. Settings -> Touch ID/Face ID & Passcode (Note: Touch ID is only available on 5s and
49 | newer; Face ID is available on the X or newer)
50 | 2. Capture a [screen shot][iOS Screenshot] of which includes _Turn Passcode
51 | Off_ and _Require Passcode_.
52 |
53 | ![iOS Passcode Status Example]
54 |
55 | ## Android Passcode
56 |
57 | ### Setting a Numeric/Pattern Passcode
58 | A numeric or pattern passcode can be set by:
59 |
60 | 1. Settings -> Security & Location
61 | 2. Turn Screen Lock On
62 | 3. Enter a 6 digit number for your pin, set an alphanumeric password of 6 characters or longer, OR set to pattern
63 | - If you opt for the pattern lock, see the next section
64 |
65 | ### Increase Pattern Security
66 | While patterns can be less secure than a pin or alphanumeric password, there are tactics for making this option more secure if you prefer this route.
67 |
68 | 1. Turn off "Make Pattern Visible." This will hide the visual path as you move your finger on the screen. How to set:
69 | - Go to settings -> security -> screen lock (gear icon/ settings)
70 | - Turn off the toggle for "Make Pattern Visible."
71 | 2. Choose a pattern that crosses over itself. In other words, avoid patterns that could be solved by tracing the leftover marks on your screen.
72 | 3. Set Fingerprint ID as your primary option and use the pattern as a backup (if the option is available to you)
73 |
74 | ### Fingerprint ID
75 | Some Android devices support Fingerprint security. Once a 6 or greater
76 | passcode has been set, Fingerprint ID is absolutely acceptable.
77 |
78 | ### Setting Passcode Activation Period
79 | Passcode activation period is the time after which an idle iPhone or iPad will
80 | require a passcode. This can be set by:
81 |
82 | 1. Settings -> Security & Location
83 | 2. Screen Lock gear icon
84 | 3. Choose a time of _5 minutes_ or less.
85 |
86 | ### Capturing Status
87 |
88 | 1. Settings -> Security & Location
89 | 2. Capture a screen shot which includes _Screen Lock_
90 | 3. Touch the gear icon next to Screen lock
91 | 4. Capture a screen shot which includes _Automatically lock_ setting
92 |
93 | ![Android Passcode Status Example1]
94 | ![Android Passcode Status Example2]
95 |
96 | [iOS Screenshot]: https://support.apple.com/en-us/HT200289
97 | [iOS Passcode Status Example]: ./ios-passcode-status.png
98 | [Android Passcode Status Example1]: ./android-passcode-status1.png
99 | [Android Passcode Status Example2]: ./android-passcode-status2.png
100 |
--------------------------------------------------------------------------------
/code-style/javascript/README.md:
--------------------------------------------------------------------------------
1 | # JavaScript
2 |
3 | [![JS Logo][producti]][product]
4 |
5 | We write a lot of JavaScript. As the Web continues to grow and as users expect more dynamic interaction with websites, JavaScript has taken on an increasingly large role. However, we believe that it's also important to know when _not_ to use JavaScript. We prefer semantic HTML and CSS solutions whenever possible, and only reach for JavaScript to enhance these capabilities. We find that this approach helps to ensure that our work is accessible to the largest number of people possible.
6 |
7 | ## Style
8 |
9 | Consistent code styling helps our teams work together better and can help prevent common JavaScript pitfalls. We rely heavily on manual code reviews to ensure the quality and functionality of the code we're writing, but prefer to automate code style enforcement as much as possible.
10 | We use [ESLint][eslint] with a [custom configuration][eslint_config] to help enforce consistent code style.
11 |
12 | ## Modern Code, Old Browsers
13 |
14 | Browser support is a constantly moving target. While we like to be forward-thinking with our code, it's also important to remain backwards-compatible. We use [Babel][babel] and [Webpack][webpack], along with appropriate [polyfills][polyfill], to allow us to use the most modern and awesome features of JavaScript while supporting the widest range of browsers.
15 |
16 | ## Static Types
17 |
18 | We like the dynamic nature of JavaScript, but we also recognize the usefulness of static type checking. We like to use [TypeScript][typescript] when the need arises.
19 |
20 | ## Frameworks / Libraries
21 |
22 | JavaScript has a rich ecosystem of libraries. Here are some of the tools we like to use.
23 |
24 | - [React][react] - A view library for building user interfaces
25 | - [Vue][vue] - Another view library for building user interfaces
26 | - [Redux][redux] - A state management library
27 | - [Axios][axios] - An [isomorphic][isomorphic] HTTP client
28 | - [Lodash][lodash] - A utility library packed full of useful functionality
29 | - [Moment][moment] - A date/time library
30 | - [Chartist][chartist] - A responsive chart library
31 |
32 | ## Testing
33 |
34 | Automated testing is an important part of our development process. Here are some of the tools we use to test.
35 |
36 | - [Mocha][mocha] - A test runner
37 | - [Chai][chai] - A test assertion library
38 | - [Sinon][sinon] - A test mocking library
39 | - [jsdom][jsdom] - A Node.js implementation of various browser APIs, useful for testing [DOM][dom] behavior
40 | - [Enzyme][enzyme] - A utility for testing React components
41 | - [Jest][jest] - Another test runner
42 |
43 | ### Mocha vs Jest comparison
44 |
45 | Mocha is a fast, highly-configurable test runner but does not provide assertions or mocking out of the box. At Sparkbox, we typically use a combination of Mocha + Chai + Sinon, rolling in jsdom or Enzyme when appropriate for component testing.
46 |
47 | Jest, on the other hand, provides a complete "out of the box" testing solution, including assertions, mocking, and jsdom with zero configuration. The downside of Jest is that it can run significantly slower than Mocha, particularly with large test suites.
48 |
49 | When choosing a test runner, a general guideline is
50 | - For speed and configurability, choose Mocha
51 | - For ease-of-use and developer experience, choose Jest
52 |
53 | [product]: https://developer.mozilla.org/en-US/docs/Web/JavaScript
54 | [producti]: ./js.svg
55 | [eslint]: https://eslint.org/
56 | [es6]: https://exploringjs.com/es6/
57 | [import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
58 | [spread]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax
59 | [babel]: https://babeljs.io/
60 | [webpack]: https://webpack.js.org/
61 | [polyfill]: https://developer.mozilla.org/en-US/docs/Glossary/Polyfill
62 | [typescript]: https://www.typescriptlang.org/
63 | [eslint_config]: https://github.com/sparkbox/eslint-config-sparkbox
64 | [react]: https://reactjs.org/
65 | [vue]: https://vuejs.org/
66 | [redux]: https://redux.js.org/
67 | [axios]: https://github.com/axios/axios
68 | [lodash]: https://lodash.com/
69 | [moment]: https://momentjs.com/
70 | [chartist]: https://gionkunz.github.io/chartist-js/
71 | [isomorphic]: https://en.wikipedia.org/wiki/Isomorphic_JavaScript
72 | [mocha]: https://mochajs.org/
73 | [chai]: https://www.chaijs.com/
74 | [sinon]: https://sinonjs.org/
75 | [jsdom]: [https://github.com/jsdom/jsdom]
76 | [enzyme]: [https://airbnb.io/enzyme/]
77 | [jest]: https://jestjs.io/
78 | [dom]: [https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model]
79 |
--------------------------------------------------------------------------------
/design/design-design_tools.md:
--------------------------------------------------------------------------------
1 | # The Design Tools We Use and Why We Use Them
2 |
3 | ## Sketch for Creating Comps
4 | We use Sketch to create comps for websites. Sketch is particularly good at mocking up UIs because of how it blends vector and bitmap artwork. Comps created in Sketch are used to communicate a design vision to the client and our team, not necessarily to show exactly what a website will look like.
5 |
6 | We use a team-based license for Sketch. Talk with the Creative Director to set that up.
7 |
8 | ## InVision for Design Communication
9 | InVision acts as a hub for design-centric communication between us and clients. It provides a few different features that help us communicate design ideas:
10 |
11 | - **Mood Boards:** Early in a design process, it can be helpful to collect a bunch of images that communicate a specific look and feel to aim for. InVision lets us upload images to a board and provides features for sharing them with our team and clients.
12 | - **Syncing:** InVision lets us upload comps in order to get feedback from clients. This is the best way to make our Sketch files viewable by clients. The most convenient way to sync from Sketch to InVision is by using InVision's [Craft plugin](https://www.invisionapp.com/craft).
13 | - **Commenting:** When comps are uploaded to InVision, notes and comments can be added by anybody viewing them. When comments are added, they exist in a physical space in the comp, which makes them useful for discussing specific parts of a design.
14 | - **Prototyping:** Interactivity can be added to comps by using the Craft plugin's prototyping functionality. When installed, select a layer, press the `C` key, and select an artboard. This will create a hot spot from the layer to the artboard. After syncing to InVision, click the hot spot to navigate to the associated artboard. By chaining these together, we can create navigable prototypes of our comps. **Note:** Craft's prototyping is a separate feature from Sketch's native prototyping. Prototyping can also be done entirely within InVision. We’ve had the most success using Craft’s prototyping features in Sketch.
15 | Talk to the Creative Director to be added to the Sparkbox team on InVision.
16 |
17 | ## Photoshop and Illustrator for Creating Artwork
18 | We use Photoshop and Illustrator to create original artwork and to modify existing assets. While they're more complex than newer tools, they're also the most fully-featured. Photoshop is unmatched when it comes to manipulating photos. Illustrator is good at generating complex, vector artwork. We often use these tools to work directly with assets, then import the assets into Sketch.
19 |
20 | Talk with the Executive Assistant to set up licensing for the Adobe Suite.
21 |
22 | ## Flinto/Principle for Advanced Prototyping
23 | Sketch and InVision work well for prototyping interactive flows, but they don’t provide many options for animation. To prototype animations or interactions, we use tools like Flinto and Principle. These provide a simple interface for creating rich, high-fidelity animations between multiple states.
24 |
25 | **Note:** using these tools, it's easy to create effects that are impossible or unwise to implement. Keep this in mind while designing.
26 |
27 | ## CodePen
28 | We use CodePen to flesh out design ideas within the browser. We can start from scratch, fork an existing pen, or bring in an existing CSS stylesheet or script. This lets us create and share deliverables that are closer to the end product.
29 | Sparkboxers get free Pro accounts. Talk with the Executive Assistant to set that up.
30 |
31 | ## Abstract
32 | Abstract is a service that provides version control for design files. This lets us iterate on designs in a structured way, which can be helpful for larger projects involving multiple designers.
33 |
34 | ## Other Resources
35 |
36 | ### Fonts
37 | Webfonts can come from a variety of different sources.
38 |
39 | - Fonts.com (credentials in 1Password)
40 | - Typography.com (credentials in 1Password)
41 | - Fonts.google.com (free, no account needed)
42 |
43 | When using paid font services, we generally use Sparkbox’s accounts for early development and smooth setup, then have the client set up their own accounts before things make it to production.
44 |
45 | ### Noun Project
46 | Drawing custom icons isn't always a good idea. The Noun Project provides a massive library of vector icons. We can download and use SVGs while creating comps. To buy icon licenses for use in production, talk to the Creative Director.
47 |
48 | ### Other Tools
49 |
50 | **Colorable:** A tool that lets us test the contrast of two given colors. This is useful to ensure our colors meet accessibility guidelines.
51 |
52 | **Skitch:** A tool for creating annotated screenshots. This is useful for decomping and providing design feedback.
53 |
--------------------------------------------------------------------------------
/security/security_principles/README.md:
--------------------------------------------------------------------------------
1 | # Security Principles for Developers
2 |
3 | Security on the web relies on confidentiality, integrity, and availability. We are able to produce robust security control by considering each of these key pieces while we build software. The following security principles embody these ideals.
4 |
5 | ## Defense in Depth
6 |
7 | **A secure application has multiple layers of security controls.**
8 |
9 | Defense in depth is the idea that security should have layers. Multiple layers of security controls make severe vulnerabilities difficult for an attacker to exploit.
10 |
11 | For example, a flawed administrative interface is unlikely to be vulnerable if it gates access to networks, checks for admin user authorization, and logs all access.
12 |
13 | ## Positive Security Model
14 |
15 | **A secure application defines what is allowed and rejects everything else.**
16 |
17 | For example, if we’re using the positive security model while working with a form input, we should specify only what characters will be allowed. That may mean only alphanumeric characters are allowed or only numbers are allowed, for example.
18 |
19 | Another example is in user access control, where a user would be allowed access only to what is needed and denied access to everything else.
20 |
21 | ## Fail Securely
22 |
23 | **A secure application handles errors and exceptions securely.**
24 |
25 | Handling errors securely is a key aspect of secure coding. Exceptions that occur while processing a security control deserve special attention. These exceptions must not allow behavior that the control wouldn’t normally allow. Any time we implement a security mechanism, there are three possible outcomes:
26 |
27 | * Allow the operation
28 | * Disallow the operation
29 | * Exception
30 |
31 | Generally, we design security mechanisms so that failure, or exception, is the same as disallowing the operation.
32 |
33 | ## Principle of Least Privilege
34 |
35 | **A secure application gives the least amount of privilege required.**
36 |
37 | This principle encompasses user rights and resource permissions.
38 |
39 | Examples of least privilege include:
40 |
41 | * only give clients access to one external client Slack channel
42 | * only giving a server permission to a network, read access to a database table, and the ability to write a log
43 |
44 | Keep in mind that it’s often easier to give additional permissions than to take away existing permissions.
45 |
46 | ## Separation of Duties
47 |
48 | **A secure application separates duties, restricting the power of any individual.**
49 |
50 | Separation of duties manages conflict of interest by restricting any one individual’s power. It is best implemented by using role-based access control and by carefully defining what each role should be able to do.
51 |
52 | We can apply this method to environments, where developers would not have administrative access to production environments. This kind of separation ensures production changes only occur through controlled means.
53 |
54 | Another example of this method is how we write code at Sparkbox. We write modular, componentized code to limit complexity, which can limit what an attacker may be able to communicate with in an attack.
55 |
56 | ## Security by Obscurity
57 |
58 | **A secure application limits what parts of the application are revealed.**
59 |
60 | Security through obscurity means limiting what is revealed about the design or implementation of a system. For example, it's best practice not to include the `X-Powered-By` header in HTTP responses.
61 |
62 | Security by obscurity can be a weak control if you're trying to hide information that you've shared. Attackers have all the time in the world to find things we hide from them, so systems shouldn’t be reliant only on keeping details hidden.
63 |
64 | ## Do Not Trust the Client
65 |
66 | **A secure application validates information coming from the client.**
67 |
68 | This principle acknowledges that anything you send a client (a person or machine that’s consuming the application) can be tampered with. Data sent from the client to the server should not be trusted. For this reason, the backend code should validate all data and permissions.
69 |
70 | ## Additional Resources
71 |
72 | - [OWASP Top 10 Web Application Security Risks](https://owasp.org/www-project-top-ten/)
73 | - [OWASP Cross Site Scripting Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
74 | - [OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/)
75 | - [NIST Digital Identity Guidelines, Section 5: Authenticator and Verifier Requirements](https://pages.nist.gov/800-63-3/sp800-63b.html#sec5)
76 | - [Juice Shop](https://github.com/bkimminich/juice-shop)
77 | - [Burp Suite](https://portswigger.net/burp)
78 |
--------------------------------------------------------------------------------
/platforms/hosting.md:
--------------------------------------------------------------------------------
1 | # Hosting
2 |
3 | We often need to make hosting decisions when building products for our clients. In general, we embrace cloud-based hosting because of its low cost, flexibility, ease of use, and ability to scale.
4 |
5 | There lots of hosting options, so it can be useful to divide them into two major categories: Infrastructure as a Service (IaaS) and Platform as a Service (Paas).
6 |
7 | ## Categories
8 |
9 | | | Infrastructure as a Service (IaaS) | Platform as a Service (Paas) |
10 | | --------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
11 | | Examples | AWS, Rackspace, Digital Ocean | Heroku, Netlify, Platform.sh |
12 | | Common features | Root access, server selection, OS selection, etc. | Built-in support for SCM integration, environments, secrets, CI, etc. |
13 | | Cost | Usually lower (not including developer time) | Usually higher (not including developer time) |
14 | | Maintenance | Requires environment setup and routine maintenance | Minimal |
15 | | Scalability | Good | Good |
16 | | Main benefit | Lots of control / customization | Very productive if it fits what you need |
17 |
18 | **Note**: many providers, like AWS, offer services in both the IaaS and PaaS categories
19 |
20 | ## Considerations
21 |
22 | The category and hosting service we select depends on our client's needs. Here are some factors that could influence our decision:
23 |
24 | - Existing hosting services that the client team is using or familiar with
25 | - Size and operational experience of the client's technical team
26 | - Expected scale of the client's project (or future projects)
27 | - Need for customization
28 | - Technologies we will be using
29 |
30 | Below is an overview of some of the hosting services we've used successfully in the past.
31 |
32 | ### AWS
33 |
34 | Amazon Web Services (AWS) is one of the earliest and most common cloud infrastructure providers around. They have a massive ecosystem of services that all integrate with each other, giving developers a lot of control in how they build out their products.
35 |
36 | The ubiquity of AWS makes it easy to find tooling and documentation around their products. It also makes finding developers with prior AWS experience easy. AWS often uses metered pricing, which can make it difficult to predict final costs (though [their calculators](https://calculator.aws) can help with this).
37 |
38 | ### Rackspace
39 |
40 | Rackspace is a mature hosting service that provides virtual machines for end-to-end hosting needs. Rackspace offers good customer support, predictable pricing, and full control over the machines you are using.
41 |
42 | ### Heroku
43 |
44 | Heroku is a managed hosting platform that allows developers to focus on building their application. Heroku uses knowledge of the application to manage builds, deploys, and scaling. For example, with a `git push`, Heroku can scan the codebase, identify the application, choose an environment, install dependencies, and deploy. This ease-of-use comes with some constraints (ephemeral file system, Heroku-specific constructs, etc), but Heroku provides sane defaults and the ability to configure custom workflows depending on needs.
45 |
46 | Hosting with Heroku can become expensive, especially as it scales, but this is offset by reducing operational setup and ongoing maintenance.
47 |
48 | ### Netlify
49 |
50 | Netlify is a robust hosting platform for static websites. This focus allows them to automate frontend workflows and provide services for backend features that static sites often need. For example, we can add features like SSL certs, form submission, serverless functions, and basic password protection with just a few clicks in the dashboard.
51 |
52 | Like Heroku, Netlify hosting can become expensive as it scales, but it offers easy setup, SCM integration, and a generous free tier, which makes it a good fit for quick experiments, design systems, and other static projects.
53 |
54 | ### Application-specific hosting
55 |
56 | Some hosting services are designed with specific applications in mind. This can help automate deployment and streamline common workflows. Here are some examples of these kinds of hosting services that we've used successfully in the past:
57 |
58 | - Acquia (Drupal)
59 | - Pantheon (Drupal/Wordpress)
60 | - Shopify (ecommerce)
61 |
62 | ## Conventions
63 |
64 | See [this document for server naming conventions](../naming_conventions/servers.md).
65 |
--------------------------------------------------------------------------------
/interviews/technical-exercises.md:
--------------------------------------------------------------------------------
1 | # Technical Exercises
2 |
3 | Sparkbox uses take home, [technical exercises] to help guage [fluency][sparkbox-values]. We know this is incredibly difficult to do efficiently without putting an undo burden on applicants and it is also difficult to do without some level of bias.
4 |
5 | The parameters of our technical exercises include:
6 |
7 | * Exercises should provide no meaningful business value to Sparkbox outside of helping to assess fluency.
8 | * Exercises should be able to be completed in approximately 4 hours for most developers, but we clearly ask applicants to take no more than 8 hours maximum. This is well beyond a reasonable amount of time to ask.
9 | * Exercises can be completed on the applicants own schedule; there is no expiration.
10 | * Criteria on which exercises will be reviewed should be clear and included with the exercise.
11 | * Incomplete submissions are accepted and a pairing session can be scheduled regardless of completion to provide guidance for applicants.
12 |
13 |
14 | ## Completing a blind review
15 |
16 | Blind reviews are important, because they allow us to assess a candidate's technical exercise submissions with less bias than might otherwise occur.
17 |
18 | Blind reviews are posted in a private channel, #tech-exercises, with:
19 | 1. The exercise we requested the candidate complete
20 | 2. A link for providing feedback in Workable.com
21 | 3. The candidate's submission, primarly as a private, anonymized Sparkbox Github repository.
22 |
23 | _Note: The submission is anonymized as much as reasonably possible, but it is not foolproof._
24 |
25 | To complete a blind review:
26 |
27 | 1. Clone the redacted repository locally.
28 | 2. Follow the evaluation criteria in the exercise.
29 | 3. Complete the appropriate Scorecard in Breezy:
30 | * Each type of technical exercise (_Frontend App Developer_, _Frontend Html & CSS Developer_, etc) has a corresponding "Scorecard" in breezy.
31 | * **Quantitative Review:** For each criteria, choose either pass  or . _Note: Comments are encouraged, but optional._
32 | - **Qualitative Review:** In “Thoughts on this Candidate” use the following template to provide qualitative feedback:
33 |
34 | > **Recommendation:** Advance the applicant. Possible Developer 2 or early Developer 3
35 | > **Qualitative review:** This is a nice solution overall. A few things that stood out:
36 | > * Structure is easy to follow
37 | > * Used XYZ element appropriately
38 | > * Nice use of framework feature X
39 | > * ABC is a nice bonus"
40 |
41 | ## Preparing Blind Reviews
42 | To do this, we:
43 |
44 | ### 1. *Anonymize the submission*
45 |
46 | Clone the submitted repository to an anonymous folder based on the Workable entry ID. This ID can be found by navigating to the candidate and finding the ID in the URL: `https://sparkbox.workable.com/backend/jobs/:job-id:/browser/2nd-interview/candidate/:candidate-id:`
47 |
48 | ```
49 | clone sparkbox-tech-exercise-:candidate-id:
50 | ```
51 |
52 | You now have the repository locally, but it still has the candidate's identifying information in the commit history. To remove it, we'll use [`git-anonymize`](https://github.com/cvortmann/git-anonymize).
53 |
54 | ```
55 | cd sparkbox-tech-exercise-:candidate-id:
56 | git anonymize
57 | ```
58 |
59 | [Create a private repo](https://github.com/new) in the Sparkbox organization for the anonymized repo. Push the repo to that remote:
60 |
61 | ```
62 | git remote add sparkbox git@github.com:sparkbox/sparkbox-tech-exercise-:candidate-id:.git
63 | git push sparkbox main
64 | ```
65 |
66 | ### 2. Create an feedback link in Workable
67 |
68 | Feedback will be posted in Breezy, our interviewing and hiring tool. For team and blind review feedback, we create a link that does not provide history of the candidates other interactions. It _will_ show their name, which is ok, but not great.
69 |
70 | To create this link, head to Breezy, navigate to the candidate, click the More button (3 dots), and select Share Candidate. Select "Yes" for Scorecard, "No" for Team Discussion, and "No" for Candidate Questionnaire.
71 |
72 | 
73 |
74 | ### 2. Share the repo with Anonymous reviewers
75 |
76 | Anonymous reviewers are in the #tech-exercises private channel. In this channel post a message like the following:
77 |
78 | > :tada: A blind review is needed for a candidate. Please have feedback posted within 48 hours. Thanks!
79 | >
80 | > * Exercise: [Exercise Name with a deep link][technical exercises]
81 | > * Feedback Link: Link to Breezy created in step 2
82 | > * Repository: https://github.com/sparkbox/sparkbox-tech-exercise-:candidate-id:
83 |
84 | [sparkbox-values]: https://github.com/sparkbox/standard/blob/bf409dd264db924c92909f2d477dc8b49d15539b/culture/our-foundation/README.md#our-foundation
85 | [technical exercises]: https://docs.google.com/document/u/1/d/1LcAP0ID9R3hsL90LW-Mldk2PxHQVA1EijTeX7qYU2K4/edit
86 |
--------------------------------------------------------------------------------
/culture/remote/README.md:
--------------------------------------------------------------------------------
1 | # Working with our Remote Teammates
2 |
3 | At Sparkbox, we have the opportunity to work with many different people in many different locations. Whether it's with our coworkers or our clients, sometimes, we all have to work remote.
4 |
5 | ## Tips for Non-remote Folks When Working With Remote Colleagues
6 |
7 | Let's be more inclusive of our remote coworkers and clients. Here are some ways how.
8 |
9 | - When a conversation becomes more than a quick back-and-forth on [Slack][], spin up a [Zoom][] and encourage all parties to join. It is almost impossible to read tone from text alone.
10 | - Try not to ask for things from your remote workers during lunch or outside normal working hours. "[Remote Guilt][]" is a real thing. For example, people who are remote have no way to tell that the Dayton office is pretty shut down around 4:30pm.
11 | - Join meetings 2-5 minutes early, to encourage friendly, human banter. Avoid jumping directly into tasking whenever possible.
12 | - Use a headset/headphones in public spaces. Avoid noisy or high-traffic areas, even if they don't seem loud to you.
13 | - Let people know if you're not using a headset, or if they are "on blast" in public spaces.
14 | - Activities with physical paper, whiteboards, or other items should be avoided. Use online tools such as [draw.io][] instead.
15 | - If your team is able, when one person is remote on a meeting, everyone should be remote. Find individual spaces, such as your desk, so that everyone is on the call separately.
16 | - This equalizes the speaking floor so that everyone involved has the same opportunity to share and listen, and no one person has to compete with a large conference room where the video screen is quickly forgotten.
17 | - This is a more important type of meeting setup for problem-solving or brainstorming meetings, as meetings like Stand-ups typically have time set aside for individuals to speak.
18 | - Be cognizant of causing audio feedback if you are near coworkers (such as in the big room).
19 | - Mute when you are not speaking, and always use a headset.
20 | - If you _are_ in a situation with a big group in one room and a few remote people on a call, designate a "point person" in the large group space as an advocate for your remote friends. Try to rotate the role of Remote Advocate among every member of the team if you meet often. The Remote Advocate could be responsible for the following:
21 | - Taking and posting frequent photos if there is anything physical, such as a whiteboard
22 | - Keeping digital notes
23 | - Check in on Slack to make sure sound and video are easily available to remote parties
24 | - Stop the conversation now and then and ask if anyone on the call has something to say
25 | - Take note of when a remote person seems to have something to say, potentially making room for them in the conversation.
26 | - Make your video meetings more friendly:
27 | - Set default Zoom settings to join without sound.
28 | - Use "gallery view" instead of "current speaker."
29 | - Avoid side conversations if you are in a shared meeting space.
30 | - Consider whether a meeting is even necessary. If the goal of the meeting is largely to pass along information, determine if it is better done in writing/async. Meetings are ideal for discussion, but not the best format for everything.
31 |
32 | ## Some of Our Favorite Resources
33 |
34 | Here are some links to articles and videos we love.
35 |
36 | - [Working on Distributed Teams at Mozilla][] (video) - Mozilla
37 | - [How to Build Effective Remote Teams][] - Phil Leggetter
38 | - [Why do remote meetings suck so much?][] - Chelsea Troy
39 | - [40 Lessons From 4 Years of Remote Work][] - Buffer, Courtney Seiter
40 | - [State Of Remote Work 2019][] - Buffer
41 | - [The 5 Ways We Build Trust on a Fully Remote Team and Why It’s So Valuable][] - Buffer, Hailley Griffis
42 | - [Effective Collaboration in Remote Project Management][] - Sparkbox, Caralyn Green
43 | - [The Ultimate Guide to Remote Meetings 2019][] - Slack, Deanna deBara
44 | - [All Remote][] - Gitlab
45 |
46 | [Slack]: https://slack.com/
47 | [Zoom]: https://www.zoom.us/
48 | [Remote Guilt]: https://www.themuse.com/advice/working-from-home-4-times-you-should-sign-off
49 | [draw.io]: https://www.draw.io/
50 | [How to Build Effective Remote Teams]: https://leggetter.dev/articles/how-to-build-effective-remote-teams/
51 | [Working on Distributed Teams at Mozilla]: https://blog.mozilla.org/inclusion/2019/03/20/working-on-distributed-teams/
52 | [40 Lessons From 4 Years of Remote Work]: https://open.buffer.com/remote-work-lessons/
53 | [State Of Remote Work 2019]: https://buffer.com/state-of-remote-work-2019
54 | [The 5 Ways We Build Trust on a Fully Remote Team and Why It’s So Valuable]: https://open.buffer.com/trust-remote-team/
55 | [Why do remote meetings suck so much?]: https://chelseatroy.com/2018/03/29/why-do-remote-meetings-suck-so-much/
56 | [Effective Collaboration in Remote Project Management]: https://sparkbox.com/foundry/effective_collaboration_in_remote_project_management
57 | [The Ultimate Guide to Remote Meetings 2019]: https://slackhq.com/ultimate-guide-remote-meetings
58 | [All Remote]: https://about.gitlab.com/company/culture/all-remote/
59 |
--------------------------------------------------------------------------------
/career/tech-lead-role.md:
--------------------------------------------------------------------------------
1 | # Sparkbox Tech Lead Role Description
2 |
3 |
4 | ## Overview
5 |
6 | * At Sparkbox, the tech lead is the **right hand to the Project Manager**.
7 | * The success of a tech lead is **measured by the success of the team and the project**.
8 | * To be successful, a tech lead needs to be able to **step out of the immediate coding needs of a project** to **understand**, **prepare**, and **regularly articulate the vision** of the project.
9 | * Tech lead models [how we work together](https://github.com/sparkbox/standard/blob/master/how-we-work-together.md).
10 | * A tech lead **empowers and unlocks the team** through communication, leadership, technical skills, and impact.
11 |
12 |
13 | ## Competencies
14 |
15 |
16 | ### Communication & Leadership
17 |
18 |
19 |
20 | * Listens effectively, recognizing and clarifying assumptions as needed.
21 | * Acts as a mediator who facilitates discussion, often guiding the team through multiple options and varied opinions to thoughtful solutions.
22 | * Makes clear and convincing presentations during team and client discussions.
23 | * Articulates thoughts using asynchronous, distributable mediums such as long-form writing and diagrams.
24 | * Creates clear and thorough cards and pull requests that aid in development and testing, accounting for the target audience’s experience and context.
25 | * Advocates for the architecture and the business, by clearly communicating the state of the architecture and the impact of decisions.
26 | * Mentors and teaches developers. Clearly explains the reasoning for something when reviewing code or explaining conventions.
27 |
28 |
29 | ### Technical Skill
30 |
31 |
32 |
33 | * Expert in the shared tools of Sparkbox, for example, the terminal, Git, etc.
34 | * Knows the value of a robust build and delivery pipeline; able to create a pipeline using the tools available to a given client project.
35 | * Recognizes, can describe, and can create a valuable test suite for a given client project.
36 | * Capable of debugging the hairiest problems that the team encounters both in development and production. To this end, a tech lead knows how to deliver a system that surfaces system health and aids in diagnosing problems in development and production.
37 | * Go-to expert in one area of the codebase of a given client project; understands the broad architecture and how the parts relate to the whole.
38 | * Sought out for and provides thoughtful technical advice and weighs in on technical decisions that impact a given client project, other teams, or the client at large.
39 | * Researches and proposes new technologies, techniques, and tools that may be adopted by clients and Sparkbox.
40 | * Anticipates technical issues at the product level and makes architectural and design decisions to avoid them.
41 | * Aware of, recognizes, and capable of invoking common software design patterns to create well-factored software.
42 |
43 |
44 | ### Managing Self
45 |
46 |
47 |
48 | * Continually learns and pursues self-development; evaluating one’s own strengths and weaknesses, especially during reviews, goal setting, and 1-on-1s.
49 | * Deals effectively with pressure, remaining empathetic, positive, transparent, and persistent. Recovers quickly from setbacks.
50 | * Persistent in the face of roadblocks; dispatches them efficiently, pulling in others as necessary. Requires minimal direction/oversight.
51 | * Establishes and maintains healthy relationships with clients and others. Receives, acknowledges, and processes negative or emotion-driven situations without reacting in kind.
52 |
53 |
54 | ### Managing Projects
55 |
56 |
57 |
58 | * Stays "ahead of the project" from a planning perspective by maintaining and communicating a shared technical vision.
59 | * Works with the project manager throughout the project to understand the budget, to guide decisions, and plan reasonable iterations.
60 | * Plans and decomposes work to avoid single, large releases to encourage regular transparency of the project progress and reduce overall risk.
61 | * Regularly delivers software on-time and constantly works to communicate ever more refined estimates, especially as estimates grow.
62 | * Quickly breaks down complex problems into potential solutions, knowns, and unknowns, in order to get to solid resolutions.
63 | * Talks to the customer to understand their needs, goals, and constraints and aligns these with the technical vision of the project.
64 | * Consistently able to reduce the complexity of projects, services, and processes in order to get more done with less work.
65 | * Understands the value of relative sizing, how to lead a team in forming an economy, and how to forecast using these types of estimates.
66 | * Enables and encourages transparency, planning, and decision making with clients and the team through clear, available, and consistent communication.
67 |
68 |
69 | ### Impact
70 |
71 |
72 |
73 | * Sustains and evolves the architecture by choosing the right cards to care deeply about and contribute code.
74 | * Takes initiative to identify and solve important problems, coordinating with others on cross-cutting technical issues.
75 | * Partners with the client, PM, and design lead to drive requirements that take into account all parties' needs.
76 | * Identifies problems/risks and works to mitigate their impact.
77 | * Makes others better through code reviews, thorough documentation, technical guidance, and mentoring.
78 |
79 |
80 |
81 |
82 | ## Resources
83 |
84 |
85 |
86 | * [Making the Leap to Tech Lead (Article, Cromwell)](https://sparkbox.com/foundry/making_the_leap_to_tech_lead)
87 | * [Making the Leap to Tech Lead (Video, Cromwell)](https://www.youtube.com/watch?v=Lx8BepRpfvg&feature=youtu.be&list=PL6De8qQmbLARL4YgjgJqa3cP83EcXRIrI)
88 | * Build Right: Sustainable Software
89 | * [Full Day Slides](https://drive.google.com/open?id=1RAdv_2EtRcZEZri-zUaaFXi8supTduC__Cr97UEj4fE)
90 |
--------------------------------------------------------------------------------
/design/design-file_organization.md:
--------------------------------------------------------------------------------
1 | # Folder Structure & File Naming
2 |
3 | ## Root
4 | - **Projects**
5 | - **Internal**
6 |
7 |
8 | ## Root / -Projects
9 |
10 | This is where all of the Sparkbox projects live. Current projects are all listed using the full name of the client and/or project.
11 |
12 | When a project is completed, it is moved into an **-Archive** folder.
13 |
14 | This division of projects allows all users access to every current and past project. It also gives the option for utilizing Dropbox’s Smart Sync feature, meaning each user can decide which files they want to store locally or in the cloud.
15 |
16 |
17 | ## Root / -Projects / Project Name
18 |
19 | When you create a new project folder, the root project directory should contain six folders (with two others that are optional).
20 |
21 |
22 | 
23 |
24 | - **-UI Explorations** is kept at the top thanks to the dash notation. It is where all exploratory design files go. When beginning a project, we often create a variety of different directions before settling on a final concept. That work can be done in here without changing established symbols and design patterns.
25 | - **-UI Iterations** is where a project moves once a visual direction has been decided on. Here there is a master sketch file that holds the symbol library, and it can be further broken up into sub-folders if the project has multiple projects within it that need separate designs.
26 | - **Assets for design** contains any assets relevant to the design files (inspiration, images, fonts, etc.).
27 | - **Assets for web** contains any exported assets that developers might need when building the site (icons, compressed images, logos, etc.).
28 | - **Assets from client** includes any assets that were delivered by the client (original logo, brand guidelines, etc.).
29 | - **Documentation** includes any documentation relevant to the project (link to Google Drive with kickoff notes, budget, process images, meeting notes, retros, etc.).
30 | - **Brand Design (optional)** contains any brand design work that Sparkbox has done.
31 | - **Wireframe / UX (optional)** includes a link to wireframes Sparkbox has created for this project or the actual files.
32 |
33 |
34 | ## Root / -Projects / Project Name / -UI Explorations
35 |
36 |
37 | 
38 |
39 |
40 | Within the **UI Design** (and **Brand Design**) folders, files are named with a consistent pattern so that it is easy to know which is most current while still maintaining a project’s history. A new version of a file is added whenever there is a milestone in the project. For example, if the design direction changes, after a demo, etc.
41 |
42 | The goal is to no longer use an **Archive** tab within Sketch and instead use files to show the archived state. This allows us to use clean symbols and have smaller working files while still keeping a historical view of the project.
43 |
44 | Whoever is working on a particular file adds their initials at the end so that multiple designers can be working on the same project without overwriting each other.
45 |
46 | There is never a “final” file. Instead, the most recent numbered file is the most current file.
47 |
48 |
49 | ## Root / -Projects / Project Name / -UI Iterations
50 |
51 |
52 | 
53 |
54 | 
55 |
56 |
57 | There are two ways the **-UI Iterations** folder could be structured. Every **-UI Iterations** folder will contain a **Symbol Library** file, which will serve as the source of truth for all symbols and consistent styles across the project. It can either have a list of versioned files that use that symbol library, or it can have sub-folders like **-Foundry** or **-Newsletter** that represent specific parts of a larger project. These sub-folders should be used when the project is too large to contain in one Sketch file or to make it easier for multiple designers to work at the same time.
58 |
59 |
60 | ## Root / Internal
61 |
62 | This folder holds all relevant assets that any Sparkbox designer might need access to or find helpful as they work on projects. Current internal projects live in this folder as well and are indexed with a **-**. Here’s an example of how this folder could be structured:
63 |
64 | - **Foundry Images**
65 | - **Brand**
66 | - **Bookshelf**
67 | - **Dribbble**
68 | - **Photos**
69 | - **Resources**
70 | - **Swag and Decor**
71 |
72 |
73 | ## Root / Internal / -Foundry Images
74 |
75 | The Foundry Images folder contains these folders:
76 |
77 | - **Exported Final Images** includes all the exports of approved Foundry images in their compressed format
78 | - **Working Images** includes all the active art files
79 | - **In Article Images** includes in-article images for posts that contain those. Inside this folder is a folder for each post that is named in the same format as a Foundry image (see below).
80 | - **Video Graphics** includes graphics and artwork produced for videos. Inside this folder is a folder for each post that is named in the same format as a Foundry image (see below).
81 |
82 | Foundry images and in-article image folders are named using the following convention:
83 |
84 | **Author's First Initial-Last Name_year-month**
85 |
86 | Example: **r-tarr_19-10.jpg**
87 |
88 |
89 | ## Conclusion
90 |
91 | This structure should be re-evaluated if the system is no longer helping to keep us organized or supporting the way we work. It should never create more work but instead make it easier for us to work together.
92 |
93 | ## Reference
94 |
95 | - Creative Market’s re-organization - one https://medium.com/building-creative-market/designing-better-file-organization-d0a3c0de9906
96 | - Creative Market’s re-organization - two https://medium.com/building-creative-market/redesigning-even-better-file-organization-part-ii-fde12128d6ac
97 |
--------------------------------------------------------------------------------
/project_management/site_completeness_checklist.md:
--------------------------------------------------------------------------------
1 | # Site Completeness Checklist
2 |
3 | ## Early Dev Checklist
4 |
5 | ### Hosting
6 |
7 | * [ ] Automated Deployments
8 | * [ ] Preproduction Environments: Disallows indexing
9 | * [ ] Preproduction Environments: Require Basic Authentication
10 | * [ ] Preproduction Environments: Whitelist the Sparkbox network - [instructions] (./project_management/htaccess_snippets.md)
11 | * [ ] Purchase CMS license (if applicable)
12 | * [ ] Transition/Purchase Font accounts in Customer Specific Account
13 |
14 | ### DevOps
15 |
16 | * [ ] Record deployments using a service like [Rollbar]
17 | * [ ] Capture and Monitor ongoing performance using a service like [NewRelic]
18 | * [ ] Assure log rotation is in place using a utility like [LogRotate]
19 | * [ ] Require SSL
20 |
21 | ### Design
22 |
23 | * [ ] Hi-Res (retina-ready) images for any images that are vector/text
24 | based
25 | * [ ] favicon.ico - use [favicon generator](http://realfavicongenerator.net), seriously.
26 |
27 | ### Content
28 |
29 | * [ ] 404 page
30 | * [ ] search results page
31 | * [ ] copyright page
32 | * [ ] terms of use page
33 | * [ ] any other legal page
34 | * [ ] credit page / sparkbox link
35 | * [ ] humans.txt included
36 | * [ ] robots.txt file pointing to sitemap.xml
37 | * [ ] sitemap.xml
38 | * [ ] meta tags (description)
39 | * [ ] page titles appropriate and SEO
40 | * [ ] imgs with alt text
41 | * [ ] img title attributes appropriate and SEO
42 |
43 | ### Markup/CSS/JS Related
44 |
45 | (in dynamic content)
46 | * [ ] basic link styles
47 | * [ ] blockquotes
48 | * [ ] unordered lists
49 | * [ ] ordered lists
50 | * [ ] all 6 header tags
51 | * [ ] inline images (left, right, center, etc in CMS content)
52 | * [ ] print stylesheet
53 | * [ ] jump to content link near top of markup (for accessibility)
54 | * [ ] check for empty (href=#) links
55 | * [ ] dynamically generated copyright date
56 | * [ ] form validation in place
57 | * [ ] error styles
58 | * [ ] form required fields tested
59 | * [ ] forms submit properly
60 | * [ ] HTML validated
61 | * [ ] CSS validated
62 | * [ ] No JS errors
63 | * [ ] CSS in the header
64 | * [ ] JS in the footer
65 | * [ ] Run Through [a11yproject](http://a11yproject.com/checklist.html) accessibility checklist
66 | * [ ] Automated [cache-busting](https://css-tricks.com/strategies-for-cache-busting-css/) of CSS and JS assets
67 | - Consider the Sparkbox [cachebust package](https://github.com/sparkbox/cachebust) for node builds
68 | ### Testing
69 |
70 | Desktop
71 | * [ ] are we going to have compatibility mode issues in IE?
72 | * [ ] content accessible in IE 7,8,9
73 | * [ ] design/content right in IE 9/10
74 | * [ ] design/content right in Micrsoft Edge
75 | * [ ] design/content right in latest PC Chrome
76 | * [ ] design/content right in latest PC FireFox
77 | * [ ] design/content right in latest Mac Safari
78 | * [ ] design/content right in latest Mac Chrome
79 | * [ ] design/content right in latest Mac FireFox
80 | * [ ] design right on a retina display
81 |
82 | Devices
83 | * [ ] design/content right in iOS phone
84 | * [ ] design/content right in iOS tablet
85 | * [ ] design/content right in Android phone
86 | * [ ] design/content right in Android tablet
87 | * [ ] design/content right in Blackberry phone
88 | * [ ] design/content right in Blackberry tablet
89 | * [ ] design/content right in Kindle tablet
90 | * [ ] design/content right in Windows phone
91 | * [ ] design/content right in Windows tablet
92 |
93 | ### Plan Launch
94 |
95 | * [ ] Determine hosting solution.
96 | * [ ] Determine launch plan. (staging environment, DNS changeover, etc)
97 | * [ ] Get client’s google tracking ID.
98 | * [ ] Get client’s mail marketing (mailchimp) ID.
99 | * [ ] Get client’s social share ID’s.
100 | * [ ] Get client’s social pages.
101 |
102 | ---
103 |
104 | ## Launch Checklist
105 |
106 | * [ ] allow indexing
107 | * [ ] Markup/CSS/JS Related
108 | * [ ] include google analytics (proper UA string)
109 | * [ ] Un-Comment-Out the Google Analytics ID so it works post launch.
110 | * [ ] ensure local jquery files are in place
111 | * [ ] local jquery version should be same as google jquery version
112 | * [ ] add selectivizr only if needed
113 | * [ ] add modernizr only if needed
114 | * [ ] build custom version of modernizr (keep file small)
115 | * [ ] Transition Typeography.com fonts to Production mode
116 | * [ ] Assure [assets are fingerprinted](https://sparkbox.com/foundry/automation_ftw_bust_your_cache) possibly with [`cachebust`](https://github.com/sparkbox/cachebust)
117 |
118 | ### Server Related
119 |
120 | * [ ] The site is backed up
121 | * [ ] Using expires headers
122 | * [ ] Using gzip
123 | * [ ] Minifying and combining our CSS
124 | * [ ] Include caching option
125 | * [ ] Page weight has been tested and is acceptable.
126 |
127 | ## Post Launch Checklist
128 |
129 | ### Project Management Related
130 |
131 | After we launch a site, this is the procedure that we will follow. We
132 | will wait approximately 14 days to allow for last minute changes,
133 | bugs, etc.
134 |
135 | * [ ] send thank you note after final payment is received and remind of
136 | 30-day support timeframe
137 | * [ ] Send documentation to client. (Check that code is commented well,
138 | send plugin list, any live or documented training)
139 | * [ ] Archive live code. (Repository or Basecamp.)
140 |
141 | ### Marketing
142 |
143 | * [ ] Submit to Galleries
144 | * [ ] Add to sparkbox.com work section
145 | * [ ] Blog about launch
146 | * [ ] Tweet from @hearsparkbox
147 | * [ ] Request client quote/recommendation (if appropriate).
148 |
149 | ### Gallery Submittal:
150 |
151 | 1. [ ] We do a “normal submission” on www.awwwards.com because
152 | it is well respected and well screened
153 | http://www.awwwards.com/submit
154 | for around $21
155 |
156 | 2. [ ] Then we use http://thecssgallerylist.com/ for sheer volume to
157 | submit to 100 other sites (hitting many popular ones) for $20.
158 |
159 | 3. [ ] Then we hand-submit the site to a few other purposeful (but free)
160 | galleries such as:
161 | mediaqueri.es
162 | http://www.mobileawesomeness.com/
163 | http://creattica.com/
164 |
165 | [Rollbar]: https://rollbar.com
166 | [NewRelic]: https://newrelic.com
167 | [LogRotate]: https://support.rackspace.com/how-to/understanding-logrotate-utility/
168 |
--------------------------------------------------------------------------------
/security/security_policy_compliance/policy-checks.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 |
3 | function start {
4 | echo "*****************************************************"
5 | printf "* $1...\n";
6 | }
7 |
8 | function fail {
9 | DETAILS=$1
10 | HELP_URL=$2
11 |
12 | echo "❌ \033[1;31m${DETAILS}\033[0m";
13 | if [ "${HELP_URL}" != "" ]; then
14 | echo "\n\033[1;37m${HELP_URL}\031"
15 | fi
16 | echo ""
17 | }
18 |
19 | function success {
20 | DETAILS=$1
21 |
22 | echo "✅ \033[1;32m${DETAILS}\033[0m\n";
23 | }
24 |
25 | function warning {
26 | DETAILS=$1
27 | HELP_URL=$2
28 |
29 | echo "⚠️ \033[1;33m ${DETAILS}\033[0m";
30 | if [ "${HELP_URL}" != "" ]; then
31 | echo "\033[1;37m${HELP_URL}\031"
32 | fi
33 | echo ""
34 | }
35 |
36 | function get_volume_attribute {
37 | NEEDLE=$1
38 | HAYSTACK=$2
39 | echo $(echo "$HAYSTACK" | grep -e "$NEEDLE:" | cut -d : -f2 | sed 's/^ *//g')
40 | }
41 |
42 | function validate_time_machine {
43 | start "Checking Time Machine Backup Disk Encryption"
44 |
45 | # Replace spaces with three underscores so we can use spaces as a delimiter in an array
46 | TIME_MACHINE_CONFIGURATION=$(tmutil destinationinfo)
47 | TIME_MACHINE_VOLUMES=$(tmutil destinationinfo | grep -e "Name" | sed 's/Name.*: //' | sed -e "s/ /___/g")
48 |
49 | if [ "${TIME_MACHINE_CONFIGURATION}" == "tmutil: No destinations configured." ]; then
50 | success "Backups are not configured. Encryption not required."
51 | elif [ "${TIME_MACHINE_VOLUMES}" == "" ]; then
52 | warning "No backup disks configured with Time Machine." "https://github.com/sparkbox/standard/blob/main/security/security_policy_compliance/timemachine.md#first-time-setup"
53 | fi
54 |
55 | for VOLUME in $TIME_MACHINE_VOLUMES; do
56 | VOLUME_NAME=$(echo ${VOLUME} | sed -e "s/___/ /g")
57 | VOLUME_INFO=$(diskutil info "${VOLUME_NAME}" 2> /dev/null)
58 | VOLUME_TYPE=$(get_volume_attribute "Type (Bundle)" "${VOLUME_INFO}")
59 |
60 | case $VOLUME_TYPE in
61 | # APFS volumes will identify their encryption status under "FileVault"
62 | "apfs")
63 | VOLUME_ENCRYPTED=$(get_volume_attribute "FileVault" "${VOLUME_INFO}")
64 | ;;
65 | # Core Storage volumes (Journaled HFS+) will identify their encryption status under "Encrypted"
66 | *)
67 | VOLUME_ENCRYPTED=$(get_volume_attribute "Encrypted" "${VOLUME_INFO}")
68 | ;;
69 | esac
70 |
71 | case $VOLUME_ENCRYPTED in
72 | Yes)
73 | success "\"${VOLUME_NAME}\" is encrypted."
74 | ;;
75 | No)
76 | fail "\"${VOLUME_NAME}\" is not encrypted." "https://github.com/sparkbox/standard/blob/main/security/timemachine.md"
77 | ;;
78 | *)
79 | fail "Unable to locate \"${VOLUME_NAME}\". Please check your connection to this volume and try again."
80 | ;;
81 | esac
82 | done
83 | }
84 |
85 | function validate_full_disk_encryption {
86 | start "Checking for FileVault full disk encryption"
87 | FILEVAULT_STATUS="$(fdesetup status)"
88 |
89 | echo "${FILEVAULT_STATUS}" | grep 'FileVault is On' &> /dev/null
90 | if [ $? != 0 ]; then
91 | fail "${FILEVAULT_STATUS}" "https://github.com/sparkbox/standard/blob/main/security/filevault.md"
92 | else
93 | success "${FILEVAULT_STATUS}"
94 | fi
95 |
96 | }
97 |
98 | function get_major_version {
99 | echo $@ | awk -F '.' '{print $1}'
100 | }
101 |
102 | function get_minor_patch_versions {
103 | echo $@ | awk -F '.' '{print $2 "." $3}'
104 | }
105 |
106 | function validate_software_updates {
107 | start "Checking for software updates"
108 | UPDATE_LIST="$(sudo softwareupdate -l 2>&1)"
109 | SUCCESS_STATUS="$(echo "${UPDATE_LIST}" | grep 'No new software available\.')"
110 |
111 | if [ "${SUCCESS_STATUS}" != "" ]; then
112 | success "${SUCCESS_STATUS}"
113 | return
114 | fi
115 |
116 | # The string to search for macOS updates
117 | OS="Title: macOS"
118 |
119 | # find all updates that are not OS updates
120 | REQUIRED_SOFTWARE_UPDATES="$(echo "${UPDATE_LIST}" | grep "Title: " | grep --invert-match "$OS")"
121 |
122 | # get the user's current MacOS version
123 | MACHINE_MAC_OS_VERSION="$(sw_vers -productVersion)"
124 |
125 | # find available minor / patch version updates
126 | # updates within the same major version of the user
127 | # indicate that a minor or patch update is available
128 | # security updates are typically patches
129 | MAC_OS_UPDATE_MINOR_VERSION="$(echo "${UPDATE_LIST}" | grep "$OS" \
130 | | grep "Version: $(get_major_version $MACHINE_MAC_OS_VERSION)" \
131 | | awk -F ', ' '{print $2}' | awk -F ': ' '{print $2}')"
132 |
133 | # find available major version upgrades
134 | # updates that are NOT within the user's current major version
135 | # indicate that a major version upgrade is available
136 | MAC_OS_UPDATE_MAJOR_VERSION=$(echo "${UPDATE_LIST}" | grep "$OS" \
137 | | grep --invert-match "Version: $(get_major_version $MACHINE_MAC_OS_VERSION)")
138 |
139 | # major OS version upgrades are not strictly required
140 | # due to differing needs and preferences
141 | # people may be unable to upgrade due to project dependencies
142 | # or may prefer to wait out the initial release bugs
143 | if [ "$MAC_OS_UPDATE_MAJOR_VERSION" != '' ]; then
144 | echo "⭐️ A newer Mac OS version is available. This upgrade is not required, but recommended:"
145 | echo "$MAC_OS_UPDATE_MAJOR_VERSION"
146 | echo ""
147 | fi
148 |
149 | if [ "$REQUIRED_SOFTWARE_UPDATES" = '' ] && [ "$MAC_OS_UPDATE_MINOR_VERSION" = '' ]; then
150 | success "No security updates required!"
151 | return;
152 | fi
153 |
154 | # because security updates are typically patches, they're required
155 | # this currently requires minor version updates as well, but that may be overkill
156 | if [ "$MAC_OS_UPDATE_MINOR_VERSION" != $MACHINE_MAC_OS_VERSION ]; then
157 | fail "A MacOS update is required:\n\n\tCurrent machine OS version:\t$MACHINE_MAC_OS_VERSION\n\tNeeds updated to version:\t$MAC_OS_UPDATE_MINOR_VERSION" "https://github.com/sparkbox/standard/blob/main/security/mac-updates.md"
158 | fi
159 |
160 | if [ "$REQUIRED_SOFTWARE_UPDATES" != '' ]; then
161 | fail "Software updates required:\n\n${REQUIRED_SOFTWARE_UPDATES}" "https://github.com/sparkbox/standard/blob/main/security/mac-updates.md"
162 | fi
163 | }
164 |
165 | echo "Today is $(date)"
166 |
167 | echo "Getting sudo access..."
168 | sudo ls &> /dev/null
169 | echo "";
170 |
171 | validate_time_machine
172 | validate_full_disk_encryption
173 | validate_software_updates
174 |
--------------------------------------------------------------------------------
/development_process/README.md:
--------------------------------------------------------------------------------
1 | # Sparkbox Development Process
2 | We believe in rapid iteration through four phases of software development: discover, build, improve, and release. This iteration happens repeatedly through the course of a project.
3 |
4 | ## **Discover**
5 | The discover phase ensures that we have what we need to build the right thing for our clients.
6 |
7 | ### Define Success
8 | Collaboratively defining what a successful engagement will look like upfront is critical to managing expectations both from a technical and a business perspective. That doesn’t mean that those requirements won’t evolve over the course of an engagement, but it does ensure that we’re all starting off on the same foot.
9 |
10 | ### Create A Technical Vision
11 | A well-documented technical vision is paramount to ensuring that we’re setting our development teams up for success in the build phase of our project. It’s critical that we understand exactly what we’re going to build and how we’re going to approach it from a technical standpoint. A technical vision has many components to it:
12 | - **The technologies to be used on the project**: After we know the business problems we’re trying to solve, it’s time to research which technologies are going to help us solve those problems most effectively. We don’t mold a project to fit a certain technology; we ensure we’re using the right technology for the project.
13 | - **A list of project milestones**: We’ll talk more about transparency during the build phase, but having a list of our milestones allows us to keep making steady progress towards our end goal while providing us with distinct sections to demo to our clients throughout the engagement.
14 | - **Well-groomed tasks**: These tasks should outline the necessary work for each project milestone. We believe that any developer should feel empowered to pick up any available card during their time in the build phase. To enable this, we ensure that our tasks are very clearly scoped and include any context or technical references necessary for it to be completed.
15 | - **A dependency map**: This should show the order that our tasks need to be completed in. If there’s work that needs done before bringing a larger team on board or if there are obvious bottlenecks during the build phase, we need to plan for that so we’re never blocking progress.
16 | - **A list of potential project risks**: Outlining our risks ahead of time allows us to shine a light on them sooner rather than later in the build phase. We want our cone of uncertainty, or the potential effect that those risks will have on our project, to be as small as possible. Finding a way to complete the more risky or unknown tasks as early as possible in the build phase allows for this.
17 |
18 | ## **Build**
19 | The build phase is where most of our software is created. In this phase, we provide enough structure to inspire confidence in the products we are creating while still allowing flexibility and iteration on the project requirements.
20 |
21 | ### Gain Confidence Through Automation
22 | - Automated build pipeline
23 | - Create the ability to quickly run the application through a gauntlet of tests and obstacles to ensure it’s ready for production before it gets there.
24 | - Automated Tests
25 | - **Unit Tests**: Test the methods and functions that make our application tick from an atomic level.
26 | - **Integration Tests**: Test the seams that are created when distinct pieces of our application are put together.
27 | - **Contract Tests**: Test the expectations we have of our service and data calls.
28 | - **User Journey Tests**: Test the experience that our users will have with our software by simulating their journeys through it (when applicable).
29 | - **Synthetic Monitoring**: Test our deployed software in the real world.
30 |
31 | ### Document Everything
32 | As a consultancy, we know we won’t always be around for our clients. Our goal isn’t to create a dependency on us but rather to empower them to fully adopt and embrace the work we do. This requires them to know how to change, maintain, and extend the software built for them.
33 | - Documentation for the business
34 | - All software exists to solve a business problem, which means even folks who were not involved in planning or building it often need to interact with it . We need to provide them with any tools and documentation needed to do this easily.
35 | - Documentation for the development team
36 | - Technical documentation is critical both during and after the software is in the build or improve phases. It allows the current development team to understand the software being built around them, and it allows any future development team to understand the context and reasoning behind why features were implemented.
37 |
38 | ## **Improve**
39 | The improve phase is where we gain insights through feedback. This could mean changing what we’re building based on stakeholder or user feedback, and that’s ok. This happens fairly often and is part of ensuring that we’re building the right thing. This is the portion of our process that allows us to be flexible.
40 |
41 | ### Enable Short Feedback Loops
42 | Short feedback loops in development are important in enabling quick iterations. Without the ability to change and deploy software from a development perspective, we cannot get new code in front of our stakeholders for review in a timely fashion. We address this by creating the automated deployment pipelines and testing suites mentioned in the build phase. When things change, as they often do in the improve phase, it’s important to keep those items up-to-date so they continue to serve the development team and enable their progress.
43 |
44 | Short feedback loops from a stakeholder and user perspective ensure we are collectively marching towards the right thing. By releasing early, we can get a feature’s MVP (minimum viable product) in front of stakeholders to gain insights in the direction we’re going. This allows us to make changes while a feature is in development instead of waiting until it’s finished before learning that it wasn’t quite right.
45 |
46 | ## **Release**
47 | The release phase is when we begin sending our built artifacts to production.
48 |
49 | ### Release Early
50 | We don’t believe in a “big bang” release structure, as this presents too much risk and not enough flexibility to ensure we’re building the right thing early on. We believe in releasing the smallest parts of our application as early as possible. This makes the flexibility required in our improve phase possible.
51 |
52 | ### Release Often
53 | Through the use of [feature flags](https://sparkbox.com/foundry/feature_flags_continuous_deployment), we can ensure that we can track our changes and roll them back quickly without a separate deploy. This mitigates a lot of the risk in deploying new features.
54 |
--------------------------------------------------------------------------------
/software/apache/README.md:
--------------------------------------------------------------------------------
1 |
2 | # Apache at Sparkbox
3 |
4 | Many of our projects, especially [CMS projects](../cms) projects, are based on PHP or require a traditional server. We tend to prefer Apache in those cases, because it's prevalent and widely used.
5 |
6 | This guide walks you through setting up Apache natively on your MacOS with the ability to support multiple versions of PHP using PHP-FPM (FastCGI Process Manager). It is based on the fantastic instructions provided by [MacOS Sierra Apache Multiple PHP Versions](https://getgrav.org/blog/macos-sierra-apache-multiple-php-versions) and [Apache httpd 2.4 and PHP 7 in macOS](https://htr3n.github.io/2017/09/apache-httpd-php-macos/)
7 |
8 | After running this setup guide, you will have 2 types of services running:
9 |
10 | 1. `httpd` Apache accepting incoming http(s) requests and matching them up with configured VirtualHost entries.
11 | 1. `php-fpm` PHP FastCGI Process Manager receiving requests from Apache to process a PHP file.
12 |
13 | PHP runs as a service to allow us to have multiple versions of PHP active for Apache at any time. Without FPM, Apache must be configured for a specific version of PHP. Switching for a project requires reconfiguring and restarting Apache.
14 |
15 | ## Steps
16 |
17 | * [Prerequisites](#prerequisites)
18 | * [Installing Xcode Libraries](#installing-xcode-libraries)
19 | * [Installing Apache](#installing-apache)
20 | * [Setting up Apache](#setting-up-apache)
21 | * [Installing PHP](#installing-php)
22 | * [Setting up a new PHP site in Apache](#setting-up-a-new-php-site-in-apache)
23 | * [Installing Composer](#installing-composer)
24 | * [Common Issues](#common-issues)
25 |
26 | ## Prerequisites
27 |
28 | * MacOS Sierra 10.12.6 or greater
29 | * Successfully run the [Sparkbox laptop](https://github.com/sparkbox/laptop) script to install Homebrew, PHP-FPM, and MySQL.
30 | * Reader must be comfortable issuing commands in the terminal
31 |
32 | ## Installing Xcode Libraries
33 |
34 | xcode-select --install
35 |
36 | ## Installing Apache
37 |
38 | Disable MacOS Apache
39 |
40 | which apachectl
41 | sudo apachectl stop
42 | sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
43 |
44 | Configure Apache (httpd), which was already installed via the [laptop script](https://github.com/sparkbox/laptop), to auto start using Homebrew services.
45 |
46 | brew services start httpd
47 |
48 | Useful commands to know:
49 |
50 | sudo apachectl start
51 | sudo apachectl stop
52 | sudo apachectl -k restart
53 |
54 | Important file locations:
55 |
56 | /usr/local/etc/httpd/httpd.conf
57 |
58 | ## Setting up Apache
59 |
60 | Edit your Apache Configuration File (`/usr/local/etc/httpd/httpd.conf`)
61 | to enable:
62 |
63 | ### Listen on port 80
64 | Change the `Listen` setting from `8080` to `80`.
65 |
66 | Listen 80
67 |
68 | ### Enable Apache Modules
69 | Uncomment out the following lines (they will not be together):
70 |
71 | LoadModule xml2enc_module lib/httpd/modules/mod_xml2enc.so
72 | LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so
73 | LoadModule proxy_module lib/httpd/modules/mod_proxy.so
74 | LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
75 |
76 | :memo: Note: `mod_proxy` will support using PHP-FPM for executing multiple
77 | concurrently installed versions of PHP.
78 |
79 | ### vhost file support
80 | Each vhost (site) will be configured in its own file in the
81 | `/usr/local/etc/httpd/vhosts` directory. Allow this to happen by:
82 |
83 | 1. Add the following line to the end of your `httpd.conf`
84 |
85 | Include /usr/local/etc/httpd/vhosts/*.conf
86 |
87 | 2. `mkdir -p /usr/local/etc/httpd/vhosts`
88 |
89 | ## PHP
90 |
91 | Multiple versions of PHP were installed and configured to run as [brew services]
92 | by the Sparkbox [laptop script](https://github.com/sparkbox/laptop). You can see each version running with
93 |
94 | brew services list | grep php
95 |
96 | Important file locations:
97 |
98 | /usr/local/etc/php/5.6/php.ini
99 | /usr/local/etc/php/7.0/php.ini
100 |
101 | ## Setting up a new PHP site in Apache
102 |
103 | ### Create the vhost file
104 | Each site will have its own _vhost_ file in `/usr/local/etc/httpd/vhosts`.
105 |
106 | :warning: You’ll need to swap out the following placeholders with your own settings:
107 |
108 | * ``: Domain safe name such as `seesparkbox`
109 | * ``: Port to the PHP-FPM instance, such as `9071` for 7.1
110 | * ``: Web root such as `/projects/seesparkbox.com/ee`
111 |
112 | :warning: You should _not_ place your Apache projects under `~/Documents`. Apache
113 | requires both write and execute permissions on all paths in the site directory,
114 | which is not advised. Instead, we recommend `~/projects` as the parent for all
115 | Apache projects.
116 |
117 |
118 | Copy, paste, & edit the following vhost configuration inside the
119 | file `/usr/local/etc/httpd/vhosts/.conf`:
120 |
121 |
122 | ServerName .local
123 | DocumentRoot ""
124 | ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:/$1
125 | ErrorLog "/usr/local/var/log/httpd/-error_log"
126 | CustomLog "/usr/local/var/log/httpd/-access_log" common
127 | DirectoryIndex index.html index.php
128 |
129 | ">
130 | AllowOverride All
131 | Options Indexes MultiViews FollowSymLinks
132 | Require all granted
133 |
134 |
135 |
136 | Save this file.
137 |
138 | ### Finishing up
139 |
140 | 1. Make sure httpd is configured to start on reboot: `brew services restart httpd`
141 | 1. Restart Apache with the changes made: `sudo apachectl -k restart`
142 |
143 | ### Add the site to your `hosts` file
144 | With `sudo` open `/etc/hosts` and add the following to the end of the file:
145 |
146 | 127.0.0.1 .local
147 |
148 | ## Installing Composer
149 |
150 | Installing composer globally.
151 |
152 | brew install composer
153 |
154 | ## Common Issues
155 |
156 | ### PHP Segfaults
157 |
158 | In PHP versions similar to 7.0.27, and httpd versions similar to 2.4.29, you might run into errors like this within your log file:
159 |
160 | [Thu Feb 15 09:16:51.849759 2018] [core:notice] [pid 3230:tid 140735914537792] AH00052: child pid 3254 exit signal Segmentation fault (11)
161 |
162 | To fix this, you must enable the `mpm_prefork_module` by adding this line to your `httpd.conf` file:
163 |
164 | LoadModule mpm_prefork_module lib/httpd/modules/mod_mpm_prefork.so
165 |
166 | :warning: **Note:** You may also need to comment out the `mpm_event_module` in order to get this to load.
167 |
--------------------------------------------------------------------------------
/project_management/README.md:
--------------------------------------------------------------------------------
1 | # Project Management
2 |
3 | ## Navigating Projects
4 |
5 | We recognize and submit to the idea that software projects are sufficiently complex and require entire teams to navigate our way to success instead of expecting to predict success at the start of a project. Success is found by navigating the waters of software development through relationships, technical challenges, ideas, and mistakes. No two projects are the same, so teams should feel empowered to adjust the process as they see fit. We only ask that they retain the principles and share their results with the rest of Sparkbox.
6 |
7 | As such, our guiding principles for navigating projects are:
8 |
9 | - **Limit surprises / Be transparent:** We do everything in our power to eliminate surprises for our clients at all times in a project. Keeping an open, honest dialogue about positive and difficult subjects is the best way we’ve found to make projects successful.
10 | - **Small, frequent increments:** Iterative delivery gives us the queues necessary to navigate early and often towards the most appropriate end.
11 | - **Shared responsibility:** Our team members and our clients share in the success and failure of our project by being timely, sharing information, and supporting one another constructively.
12 |
13 |
14 | ## Tooling
15 | Just like our dev efforts, everything is in [constant flux to best serve our clients](http://webstandardssherpa.com/reviews/responsive-discovery/) around here. Many of us adore [ZenHub](https://www.zenhub.io/) or [Trello](https://trello.com/). And we make [Jira](https://www.atlassian.com/software/) work when needed. :)
16 |
17 | We dig using the right tools for each project, which often includes [Basecamp](https://basecamp.com/) (for project updates, discussions, and file sharing) and [InVision](https://www.invisionapp.com/) (for design collaboration).
18 |
19 | When choosing tools to help our teams collaborate around work, we use the following principles as our guide:
20 |
21 | 1. Be simple
22 | 2. Be accessible
23 | 3. Efficiently surface remaining work
24 |
25 | ## Project Hub
26 | To help counter the confusion that comes with using numerous tools and repositories for large projects, we find it's helpful to create a [Project Hub (centralized repository of project information)](https://github.com/sparkbox/standard/blob/master/project_management/base-hub.md). This helps everyone access exactly what they need when they need it and can help as teammembers join the project.
27 |
28 | 
29 |
30 | _Project Hubs help consolidate all the pertinent high-level project details in one spot._
31 |
32 | ## Priorities
33 | No matter the tools, we aim to keep projects focused on goals, priorities, and removing barriers for the people doing the work and making decisions. We most often use [GitHub](https://github.com) to create user stories or other work that needs done as "Issues" to gather and communicate the scope of work that needs done in detail. We'll often use Zenhub to then provide estimates for the level of effort for those issues and to prioritize those same issues.
34 |
35 | 
36 |
37 | _Kanban boards allow you to prioritize work to stay in ultimate control over the work that gets done and when it is done. It's a great way to view priorities and work iteratively._
38 |
39 | ## Communication & Control
40 | We estimate work early and do at least weekly transparent reality checks of budgets, timelines, and project health. We share those reality checks (typically via Basecamp with the whole team) and keep you on top of where things stand so that you can make smart decisions throughout the project. Using Zenhub and other kanban boards, while working hourly and giving frequent updates gives you ultimate control over prioritization and how your budget is spent.
41 |
42 | 
43 |
44 | _Burndowns give a great visual view of project health._
45 |
46 | We like to work in iterations, and can use your priorities to create appropriate milestones—and when we match up those issues with estimates, and milestones for a project, we get the power of burndown charts. We use all of these resources and tools to keep you updated on checkins/standup calls and walk through work/progress together. We get to a testing environment early to not only _tell_ you the progress we've made, but actually show you and anyone else you want to see, the reality of where the project stands early and often.
47 |
48 | ## Team Roles
49 |
50 | Creating environments for collaboration, and having generally-defined roles is helpful as we see that development and design have great overlaps. To unlock the key potential between that strong collaborative working relationship we have outlined our first iteration of roles that we’re using and intend to refine over time.
51 |
52 | **Project Manager:** enables the team and client
53 | * Wherever possible defaults to inviting everyone to meetings and pulls back to what is adding value based on team input.
54 | * Helps spread knowledge across the team and highlights decisions that impact disciplines.
55 |
56 | **Development Lead:** enables the development team
57 | * Creates (and helps estimate) Issues/Stories
58 | * Assures high quality of code in implementation
59 | * Writes some code
60 | * Manages drops and handoff as appropriate
61 |
62 | **Development Advocate:** helps highlight decisions that impact development
63 | * Attends related meetings (UX/Content/Design)
64 | * Communicates impactful decisions across the team: bringing them up in meetings where they are being decided and bringing up the decisions to the dev team
65 | * Smaller projects: one advocate for frontend and backend
66 | * Large projects: one advocate for frontend and one for backend
67 |
68 | **Design Lead & Advocate:** enables the design team
69 | * Attends related meetings (UX/Content/Dev)
70 | * Assures high quality of design in implementation
71 | * Pairing with team
72 |
73 | **Frontend Hammer:**
74 | * Determines constraints, tooling, and solutions to make a frontend component exist
75 | * Writes the majority of code to make a frontend component exist
76 | * Shares progress with a chisel for final refinement (just like when you would have previously consulted with the designer to have your work reviewed, only the design/dev chisel will code the refinements)
77 |
78 | **Frontend Chisel:**
79 | * Primarily refines the work of others
80 | * Can fill in and create some new elements when it makes sense
81 | * Own performance from a design perspective (Image & SVG optimization)
82 | * Could be the Design Advocate
83 | * Prefer this person to not be the Hammer
84 |
85 | **UX/Content:**
86 | * Helps spread knowledge across the team and highlights decisions that impact disciplines.
87 | * Works closely with design & dev leads
88 | * Assures high quality for UX/Content in implementation
89 |
--------------------------------------------------------------------------------
/code-style/php/README.md:
--------------------------------------------------------------------------------
1 | # PHP Coding Standards
2 | 
3 |
4 | Despite being one of the most used languages for building web applications, PHP doesn't have the best reputation. We use a number of frameworks that are built with PHP. In order to avoid PHP's reputation of messy codebases, we utilize [PHP_CodeSniffer][phpcs] to detect violations of defined coding standards.
5 |
6 | ### Picking a standard
7 | Many frameworks have their own standards declared. We use the framework's defined standards when possible. For instance, when developing a WordPress theme, we utilize the [WordPress Standard][wp]. If there is not a standard defined, or we are not using a framework, we use the [PSR-2 Standard][psr-2]. These are the standards for some of our commonly used frameworks:
8 |
9 | - [PSR-2 / Default][psr-2]
10 | - [WordPress][wp]
11 | - [Symfony][symfony]
12 | - [Drupal][drupal]
13 |
14 | ### Enforcing a standard
15 |
16 | [PHP_CodeSniffer][phpcs] allows us to lint our PHP. To install PHPCS, do the following:
17 |
18 | 1. Install PHP CodeSniffer:
19 |
20 | `composer global require "squizlabs/php_codesniffer=*"`
21 | 1. Ensure you have access to global composer installs. In your .zshrc or .bashrc file, make sure you have the following:
22 |
23 | `export PATH=~/.composer/vendor/bin:$PATH`
24 |
25 | 3. Install Coding Standards:
26 |
27 |
28 | PSR-2 Coding Standard
29 | PSR-2 is installed by default with phpcs
30 |
31 |
32 |
33 | Drupal Coding Standard
34 |
35 | - Install Drupal Standard
36 |
composer global update drupal/coder --prefer-source
37 |
38 | - Register Drupal standards in PHP Codesniffer
39 |
composer global require drupal/coder:^8.3.1
40 | composer global require dealerdirect/phpcodesniffer-composer-installer
41 |
42 |
43 |
44 |
45 |
46 | Symfony Coding Standard
47 | Symfony follows PSR-2 with a few additional standards.
48 |
49 | - Install the coding standard as a dependency of your project
50 |
composer require --dev escapestudios/symfony2-coding-standard:3.x-dev
51 |
52 | - Add the coding standard to the PHP_CodeSniffer install path
53 |
phpcs --config-set installed_paths vendor/escapestudios/symfony2-coding-standard
54 |
55 |
56 |
57 |
58 |
59 | WordPress Coding Standard
60 |
61 | - Install WordPress Standard
62 |
git clone https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git ~/wpcs
63 |
64 | - Register WordPress standards in PHP Codesniffer
65 |
phpcs --config-set installed_paths /Users//wpcs
66 |
67 |
68 |
69 |
70 | 4. To verify the selected standard(s) were installed correctly, list installed standards with `phpcs -i`
71 |
72 | ### Setting Up Visual Studio Code to recognize linters
73 |
74 | **Extensions Required:**
75 | - [phpcs][phpcs_vscode]: provides integration for PHP CodeSniffer (phpcs) code linting
76 |
77 | **Extensions: Bonuses:**
78 | - [PHP DocBlocker][docblocker]: provides auto-complete for PHP docblocks
79 | - [PHP Intelephense][intelephense]: provides support for PHP code completion and intellisense that supports any PHP file extension
80 | - [PHP Intellisense][intellisense]: provides support for PHP code completion and intellisense but only for files using the PHP extension
81 | - [Drupal 8 Extensions][drupal8]
82 | - [Drupal 7 Extensions][drupal7]
83 |
84 | To see the linter in your editor, set up per-project vsCode settings.
85 |
86 | Example Drupal Standards VScode Config
87 |
88 | ```PHP
89 | {
90 | "phpcs.enable": true,
91 | "phpcs.standard": "Drupal",
92 |
93 | /* Editor Suggestions / Optional */
94 | "breadcrumbs.enabled": true,
95 | "editor.tabSize": 2,
96 | "editor.autoIndent": "full",
97 | "editor.formatOnSave": false,
98 | "editor.renderWhitespace": "boundary",
99 | "editor.wordWrapColumn": 80,
100 | "editor.wordWrap": "off",
101 | "editor.detectIndentation": true,
102 | "editor.rulers": [ 80 ],
103 | "files.associations": {
104 | "*.inc": "php",
105 | "*.module": "php",
106 | "*.install": "php",
107 | "*.theme": "php",
108 | "*.tpl.php": "php",
109 | "*.test": "php",
110 | "*.php": "php"
111 | },
112 | "html.format.enable": true,
113 | "html.format.wrapLineLength": 80,
114 | "telemetry.enableTelemetry": false,
115 | }
116 | ```
117 |
118 |
119 |
120 | Example WordPress Standards VScode Config
121 |
122 | ```PHP
123 | {
124 | "phpcs.enable": true,
125 | "phpcs.standard": "WordPress",
126 |
127 | /* Editor Suggestions / Optional */
128 | "editor.insertSpaces": false,
129 | "editor.tabSize": 4,
130 | "intelephense.files.maxSize": 3200000
131 | }
132 | ```
133 |
134 |
135 | ### Setting Up circleCI to Run Code Checker:
136 |
137 | CircleCi provides orbs, which are reusable snippets of code. Orbs help automate repeated processes, speed up project setup, and make it easy to integrate with third-party tools.
138 |
139 | These are some example orbs:
140 | - [WordPress phpcs orb][drupal_orb]
141 | - [Drupal phpcs orb][wp_orb]
142 |
143 | When a public orb doesn't fit the needs of a project, we can set up a custom CircleCi setting by modifying an existing orb or creating a new config from scratch. View a [custom WordPress config example here][wp_custom].
144 |
145 |
146 | [wp]: https://github.com/squizlabs/PHP_CodeSniffer
147 | [phpcs]: https://github.com/squizlabs/PHP_CodeSniffer
148 | [psr-2]: https://www.php-fig.org/psr/psr-2/
149 | [symfony]: https://github.com/djoos/Symfony-coding-standard
150 | [drupal]: https://git.drupalcode.org/project/coder
151 | [drupal_docs]: https://www.drupal.org/docs/8/modules/code-review-module/installing-coder-sniffer#s-register-coder-standards
152 | [phpcs_vscode]: https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs
153 | [docblocker]: https://marketplace.visualstudio.com/items?itemName=neilbrayfield.php-docblocker
154 | [intelephense]: https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
155 | [intellisense]: https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-intellisense
156 | [drupal8]: https://www.drupal.org/docs/develop/development-tools/configuring-visual-studio-code#s-drupal-8-recommended-extensions
157 | [drupal7]: https://www.drupal.org/docs/develop/development-tools/configuring-visual-studio-code#s-drupal-7-recommended-extensions
158 | [drupal_orb]: https://circleci.com/orbs/registry/orb/kanopi/ci-tools#usage-phpcs-drupal-simple
159 | [wp_orb]: https://circleci.com/orbs/registry/orb/kanopi/ci-tools#jobs-phpcs-wordpress
160 | [wp_custom]: https://github.com/rfearing/wp-phpcs-docker-circleci-example/blob/master/.circleci/config.yml
161 |
--------------------------------------------------------------------------------
/accessibility/keyboard-accessibility/keyboard-accessibility.md:
--------------------------------------------------------------------------------
1 | # Keyboard-Only Navigation
2 | Sparkbox recognizes the importance of creating a web that is accessible to everyone, so we prioritize developing and testing for accessibility as an integral part of our process. In addition to automated testing, our developers conduct ongoing accessibility tests as they build their projects. Manually testing content and custom site features for keyboard-only accessibility during this phase allows developers to identify and remediate issues before they become a problem for users.
3 |
4 | To support this approach, we incorporate keyboard-only navigation testing into both our planning and development processes. Story cards and pull requests include clear instructions for testing with a keyboard to ensure that developers and testers who may not be familiar with web accessibility concepts can still successfully participate in creating accessible work.
5 |
6 | ## Why Do We Value This?
7 | Keyboard accessibility determines how successfully a user can navigate all areas and functionality of a website using only their keyboard. Users who most commonly benefit from keyboard-only navigation are those with visual impairments and those with motor difficulties that make using a mouse difficult or impossible. Keyboard-only navigation is especially important as it serves as the basis for a wide range of assistive technologies, such as voice input and single switch entry devices.
8 |
9 | ## Developing and Testing for Keyboard Accessibility
10 | Keyboard-only navigation tests will not reflect a real user’s experience unless system-wide keyboard accessibility is enabled. Instructions for enabling keyboard accessibility on different platforms are below.
11 |
12 | #### Keyboard Accessibility on MacOS
13 | Keyboard accessibility is *not* enabled by default on a Mac. The default keyboard settings only allow the user to tab to form controls. System-wide keyboard accessibility must be enabled in both System Preferences and Safari Preferences to allow the user to be able to tab to other elements.
14 |
15 | [Enabling Keyboard Accessibility on a Mac](https://dequeuniversity.com/mac/keyboard-access-mac) (Deque University)
16 |
17 | #### Keyboard Accessibility on Windows
18 | Keyboard accessibility is enabled by default on Windows.
19 |
20 | ### Considerations to Test for
21 | Once system-wide keyboard accessibility has been enabled, test the site for the following considerations. Navigation for all of the following tests begins in the URL field of the browser.
22 |
23 | #### Tab Focusability and Tab Order
24 | The user should be able to navigate to all elements that would naturally receive focus using the Tab key to move forward and the Shift + Tab keys to move backward.
25 |
26 | The focus order of the site also determines the reading order of the content for users navigating by keyboard. By default, the focus will move to and from the next focusable element in the order that they appear in the DOM. DOM order does not always match the visual presentation of the website, so we need to test to ensure that the focus/reading order makes sense for the user. This may vary based on the site, but generally the focus should not skip to an unexpected part of the site, and the reading order should follow the same pattern that a sighted user not using keyboard-only navigation would experience.
27 |
28 | Using a positive `tabindex` value to change the tab order should be avoided. Elements with a `tabindex` greater than `1` receive keyboard focus before other elements. This can create a situation in which the focus order is not logical to the user (for example, tabbing may take the user to an element on the center of the page and then back to the beginning of the page.)
29 |
30 | #### Visual Focus Indicator
31 | As users navigate a site with a keyboard, they should always be able to see the location of the current keyboard focus. Without a visual focus indicator, keyboard users can become lost or unable to tell if they are focused on an element with which they want to interact.
32 |
33 | Sparkbox uses the [Safe Focus](https://github.com/sparkbox/safe-focus) package, which adds custom outline styles to all selectable components.
34 |
35 | #### Focus Management
36 | Dynamically generated content can make it challenging to ensure that keyboard-only users are able to keep track of keyboard focus. The following points should be taken into account when new content is generated or deleted by a user action:
37 |
38 | * When new content is added to the page, the keyboard focus should be sent to the most logical place on the page, depending on the context. For example, if the user submits a form that generates error messages for fields that are filled out incorrectly, the focus should be sent to the first field that has an error.
39 |
40 | * When content is removed from the page by a user action, the keyboard focus should be sent to the most logical place on the page, depending on the context. For example, when a user closes a modal that was generated by their action, the focus should be returned to the element that the user interacted with to generate the modal.
41 |
42 | #### Keyboard Traps
43 | Keyboard traps happen when a user is unable to navigate out of an area of a web page without having access to a non-keyboard input device like a mouse. Keyboard traps are detrimental to keyboard-only users and can potentially prevent them from interacting with the site at all.
44 |
45 | #### Keyboard Functionality
46 | When testing for keyboard functionality, ensure that all functionality that exists on a web page is available when using only the keyboard. This includes interacting with form elements and any custom widgets (such as custom form elements that do not use native HTML elements) that exist on the page.
47 |
48 | A [list of standard keystrokes for common online interactions](https://webaim.org/techniques/keyboard/#testing) can be found on WebAIM’s Keyboard Accessibility guide.
49 |
50 | Using native HTML elements is the most effective way to make a site accessible as these elements have built-in behaviors and patterns that users expect. If creating a custom widget is necessary, the widget should be developed in a way that allows keyboard users to follow the common pattern of using Tab to enter and exit the widget and using the arrow keys (↑ ↓ → ←) to navigate within the widget.
51 |
52 | #### Custom Keyboard Shortcuts and Screen Readers
53 | Navigation with the keyboard only is not the same as navigating with a keyboard and screen reader. When a screen reader is active, it allows the user to use a unique set of keyboard shortcuts to navigate and interact with their computer and the internet. These shortcuts are not available to users who are not using a screen reader, such as a sighted user who may use keyboard-only navigation rather than a mouse due to a motor disability.
54 |
55 | Ensure that any custom keyboard shortcuts do not interfere with the keyboard shortcuts used by screen readers. In addition to the common keyboard shortcuts shared by most screen readers, each screen reader may also have its own set of keyboard shortcuts. Deque University’s [Screen Reader Keyboard Shortcuts and Gestures](https://webaim.org/techniques/keyboard/#testing) is a good resource to see which keyboard shortcuts should be avoided.
56 |
57 |
58 |
59 |
60 |
61 |
62 |
63 |
64 |
65 |
66 |
--------------------------------------------------------------------------------
/services/slack/README.md:
--------------------------------------------------------------------------------
1 | # Slack
2 |
3 | [![Image of Slack][producti]][product]
4 |
5 | We use Slack to stay in touch with each other no matter where we are physically. It’s a great tool, and the following outlines a few tips to keep Slack useful—and navigable–for everyone.
6 |
7 | [product]: https://slack.com/
8 | [producti]: http://i.imgur.com/0u1iR8W.png
9 |
10 | ## Channels
11 |
12 | Slack allows us to create channels to talk to everyone at once: think "chat room".
13 |
14 | ### #general & #random
15 |
16 | By default slack has two channels, #general and #random, and all users are added. While #general is a place to talk about work related stuff, #random is a scary place of pure randomness.
17 |
18 | ### Sparkbox channels
19 | Official "Sparkbox Sanctioned" channels begin with a `-`. See the note on prefixes below.
20 |
21 | ##### #-awesomeness
22 | A channel for sharing awesome notes about coworkers.
23 |
24 | ##### #-biz
25 | A place for **bizBot** to keep Sparkbox informed about business development.
26 |
27 | ##### #-conferences
28 | The channel for sharing interesting conferences, Call for Speakers, and planning the conference you'd like to attend.
29 |
30 | ##### #-dayton & #-pittsburgh
31 | Channels to discuss office-specific happenings, such as lunch plans.
32 |
33 | ##### #-gems
34 | A collection of quotations from your Sparkbox community, curated in part by **gem-me-bot**. Share a gem publicly with the `:earth-americas:` reaction, or hide it from the public eye with the `:x:` response. There's even [a Foundry article](https://sparkbox.com/foundry/sparkbox_gems) if you'd like to learn more.
35 |
36 | ##### #-know-your-company
37 | A place to discuss fun facts about coworkers, along with weekly KYC email answers.
38 |
39 | ##### #-sparkbox-pride
40 | Share your Sparkbox Pride, generally in photo form.
41 |
42 | ### Public Channels
43 |
44 | Additional channels have been created which any member of the Sparkbox team can join at any time. These channels cover a range of topics from discussion on design, to video games, to weekly lunches. Any member of the team can start a new channel or join an existing one.
45 |
46 | ### Creating New Channels
47 |
48 | There are obvious times to create a new channel, such as when a new client engagement starts. There are also not as obvious times. When deciding to create a new channel, ask yourself these questions:
49 | - Is this channel new and not covered by any existing channels? Have I asked in #general if a similar channel exists?
50 | - Will this channel reduce ongoing unrelated clutter in another channel?
51 |
52 | After you create a new channel, be sure to set a clear, concise channel purpose so that other Sparkboxers can easily understand what the channel is discussing.
53 |
54 | **Note: Public over Private** should be the default. Even if you feel the topic is only of interest to a small number of people, consumer filtering is preferred over producer filtered content. This allows everyone to see how and why decisions are made. Just like an open-source GitHub repo. Similarly, if you have a question for one person regarding a project or a technology that might be relevant to someone else on the team, consider asking that question in the proper public channel rather than a DM.
55 |
56 | ### Naming Conventions
57 |
58 | #### Rule #1
59 | hyphens-not-underscores
60 |
61 | #### Rule #2
62 | all-lower-case
63 |
64 | #### Rule #3
65 | Including the year in a title name is generally unnecessary. This sets up a short-lived channels mindset. If you do find it necessary to set up one of those, it would be wise to go ahead and set up a calendar reminder to kill it when you likely know its usefulness would run out.
66 |
67 | #### Rule #4
68 | prefix-appropriately
69 |
70 | - `-` Important, common channels for everyone.
71 | The `-` ensures they go to the top of the channel list. A channel should get this prefix if everyone at Sparkbox would likely find value in belonging to it. *Example: `-biz`.*
72 | - `int-` Client Projects, "internal" Sparkboxer-only channels.
73 | - `ext-` Client Projects, "external" channels that may include the client team.
74 | - `temp-` Channels with a temporary purpose. You need something larger than a DM but it won’t be a permanent channel (example: conferences, Maker Series, etc.). Perhaps set up a calendar reminder to delete your channel later.
75 |
76 | ### Pruning Channels
77 |
78 | Channels can quickly become unruly and difficult to navigate. We’ve recognized two reasons to archive a channel:
79 |
80 | - Redundancy: If two or more channels serve the same purpose, then decide on the one that is most popular/used, and delete the others.
81 | - Unused: If a channel has gone silent, then a vote will be called and requires three* people voting :hand: in order to keep the channel. If less than three people vote to keep the channel, then it should be archived.
82 |
83 | Unless a channel is redundant, the default action will be to archive it, because channels can be unarchived very easily. Since archived channels don’t shown in the channel listing, archiving is a safe way to remove visual clutter and cut down on searching while still leaving the option to resurrect that channel later.
84 |
85 | #### garbage_bot
86 |
87 | The bot user, @garbage_bot is a tool created by Patrick Simpson to identify unused channels on a quarterly basis. It will notify #random with a list of channels flagged for review.
88 |
89 | ## Etiquette
90 | #### `@everyone`, `@channel`, or `@group`
91 | Try using `@here` to only notify online, desktop users. Alternatively, `@dayton` is useful to target only those in the Dayton office, or `@pittsburgh` for the Pittsburgh office. In any case, be respectful of the many people who will receive notifications, often to mobile devices on nightstands.
92 |
93 | #### Code of Conduct
94 | All Sparkbox employees are expected to follow the [Sparkbox Code of Conduct](../../culture) while participating in Slack. Treat it as you would physical office space.
95 |
96 | ## Direct Messages
97 |
98 | Not all conversations have to be public. If you need to say something in private you can send a direct message, think Instant Messenger.
99 |
100 | ## Notifications
101 |
102 | Get notified when someone mentions you in conversation, sends you a direct message or setup a list of keywords to be notified when someone mentions something important, like ping pong.
103 |
104 | 
105 |
106 | ### Twitter
107 |
108 | Slack really likes to keep everyone in the loop so it shares Twitter notifications. When someone mentions [@hearsparkbox](https://twitter.com/hearsparkbox) on Twitter it shows up in the General channel for all Sparkboxers to see.
109 |
110 | ## The App
111 |
112 | We can stay in the loop even when we are out of the office with the [mobile app](https://itunes.apple.com/us/app/slack-team-communication/id618783545?mt=8).
113 |
114 | ## Sparkbot
115 |
116 | Sparkbot is available for a number of helpful tasks. Direct message `@sparkbot` with `help` to see a full list of commands.
117 |
118 | ### Resources
119 | - [Slack’s Guide to Managing Slack](https://slackhq.com/how-to-manage-your-slack-channels-38801ef651f2#.eo5pulg6t)
120 | - [Ember Slack Naming Conventions](https://github.com/cromwellryan/embercommunity-slack-guidelines#creating-new-channels)
121 | - [Fugue’s Slack](https://blog.fugue.co/2016-03-29-it-s-not-all-unicorns-and-rainbows-managing-slack-for-productivity.html)
122 | - [Controlled Vocabulary](https://en.wikipedia.org/wiki/Controlled_vocabulary)
123 | - [Controlled Vocabulary at Microsoft](Controlled Vocabulary at Microsoft)
124 |
--------------------------------------------------------------------------------
/accessibility/introduction/README.md:
--------------------------------------------------------------------------------
1 | # General Accessibility Guidelines & Introduction
2 |
3 | ## Our Accessibility Focus at Sparkbox
4 |
5 | ### Build Right, Build Better, Build Accessibly
6 |
7 | For a long time, Sparkbox has had the goal to build right and to build a better web. In the past couple of years, we have invested in and focused on web accessibility as part of these goals: leveling up our developers with [certifications](https://www.accessibilityassociation.org/certification), bringing in people to do usability testing in person, and having a [Maker Series](https://sparkbox.com/foundry/derek_featherstone_web_accessibility_and_inclusive_design) dedicated to the topic. We believe that all websites should be built accessibly and that accessibility should be a part of our whole process rather than a task we do at the end of a project. By prioritizing accessibility, we build websites that enable a wider audience to access the web while also providing a useful and enjoyable user experience.
8 |
9 |
10 | ### WCAG 2.1 AA Principles Compliance
11 |
12 | Sparkbox aims to fulfill the principles of WCAG 2.1 AA, with an especial focus on the experiences of people with physical, hearing, and sight limitations who employ the use of screen readers or keyboard-only technology (the W3C [does not recommend](https://www.w3.org/TR/WCAG21/#cc1) requiring AAA compliance as it can be impossible to attain for certain types of content). Secondarily, we work to create good experiences for people who encounter color contrast issues and for users with cognitive disabilities. However, our user base focus may differ depending on the most common browsers or technologies utilized on our clients’ sites.
13 |
14 | We emphasize the **principles** of WCAG over the success criteria because even if someone builds a website that meets every single WCAG AAA success criterion, they may not actually create an accessible experience as a whole. Highlighting principles allows us to focus on the entire experience of the user as they browse a web page, and in this way, we can create a better and more accessible experience than just trying to “check off” boxes on an accessibility task list.
15 |
16 | ### Testing
17 |
18 | In order to create accessible websites, Sparkbox not only thinks about accessibility at each stage of the process but also conducts extensive testing. We have a set of tools we employ to give us a high-level overview of potential accessibility issues, such as [pa11y](https://pa11y.org/), [Axe](https://www.deque.com/axe/), [Lighthouse](https://developers.google.com/web/tools/lighthouse), and [Wave](https://wave.webaim.org/). However, these kinds of automated tools are only able to find 30-50% of potential accessibility issues. Thus, we also emphasize that developers and designers test with common screen reader/browser combinations and keyboard-only navigation to get a real sense of other issues that may be present. At Sparkbox, we can use our own computers, BrowserStack, our QA devices in Dayton, and Virtual Machines to do this manual testing.
19 |
20 | Since we also know that usability testing is crucial, we are working on finding a way to do user testing with people who use the technologies each day. We are excited to incorporate that into our process next.
21 |
22 | **Sources**:
23 | * [W3C: WCAG 2.1 Reference]
24 | * [Deque: How to Get Development On Board with Accessibility Testing]
25 | * [WebAIM: Accessibility User Testing]
26 |
27 | ## Accessibility is All or Nothing
28 |
29 | It is important to note, especially for legal compliance, that accessibility is all or nothing. If there is even one inaccessible part of the page, the entire website can be classified as inaccessible. We need to be aware of this as an organization and ensure that we are thinking about accessibility in each of our roles and during each stage of building a website, from discovery to design to development.
30 |
31 | ## Disability Statistics
32 |
33 | Everyone has been profoundly affected by technology and access to the web. For those living with disabilities, however, the effects have been even more meaningful and liberating. From the comfort of their home, they can now provide for themselves in many ways that were not possible before the internet. For example, people with disabilities can have jobs where they just need access to the internet to do work, can order and ship groceries to their homes, can access government and banking services online, and the list goes on.
34 |
35 | However, if we do not build our websites with a focus on web accessibility practices, we limit the access of audiences with disabilities. Depending on the report and how disability is defined, this audience constitutes somewhere from [13%][The Rehabilitation Research and Training Center on Disability * Statistics and Demographics: 2018 Annual Report] to [19%][U.S. Census Bureau: Nearly 1 in 5 People Have a Disability in the U.S.] to [27%][Americans with Disabilities: 2014 Report] of the US population. In all of the sources reporting on disability statistics, the prevalence of types of disabilities remains consistent: having a physical impairment is the most common disability, followed by cognitive disabilities, and then hearing, sight, or speech impairments.
36 |
37 | These statistics demonstrate that people with disabilities consist of a huge portion of the population. They also show that as we age, it is likely we will also develop a disability.
38 |
39 | **Sources**:
40 | * [WebAIM: Introduction to Web Accessibility]
41 | * [U.S. Census Bureau: Nearly 1 in 5 People Have a Disability in the U.S.]
42 | * [The Rehabilitation Research and Training Center on Disability * Statistics and Demographics: 2018 Annual Report]
43 | * [Americans with Disabilities: 2014 Report]
44 |
45 | ## Benefits of Web Accessibility
46 |
47 | Everyone should be able to access the web. If this weren’t reason enough for us to build accessibly, we also see the following other benefits:
48 |
49 | * A potential 27% increase of the consumer base of our websites
50 | * Decreased legal risk from ADA lawsuits
51 | * Mobile and bandwidth-friendly websites
52 | * Improved SEO and site-searchability rankings
53 |
54 | Web accessibility benefits everyone, so let’s continue building a better web, built with accessibility in mind.
55 |
56 | **Sources**:
57 | * [Americans with Disabilities: 2014 Report]
58 | * [WebAIM: Web Accessibility and SEO]
59 | * [PopArt Studio: Inclusive Design: Making Websites Accessible to Everyone]
60 |
61 | ## Accessibility Guides
62 |
63 | The following guides document the specific ways Sparkbox views and implements web accessibility related to:
64 |
65 | * [Keyboard-Only Navigation](/accessibility/keyboard-accessibility/keyboard-accessibility.md)
66 |
67 | ### Future Installments - *Coming Soon*
68 | * Screen Readers
69 | * Color Contrast
70 | * Cognitive Disabilities
71 |
72 | [W3C: WCAG 2.1 Reference]: https://www.w3.org/TR/WCAG21/
73 | [Deque: How to Get Development On Board with Accessibility Testing]: https://www.deque.com/blog/how-to-get-development-on-board-with-accessibility-testing/
74 | [WebAIM: Accessibility User Testing]: https://webaim.org/blog/accessibility-user-testing/
75 | [WebAIM: Introduction to Web Accessibility]: https://webaim.org/intro/
76 | [U.S. Census Bureau: Nearly 1 in 5 People Have a Disability in the U.S.]: https://www.census.gov/newsroom/releases/archives/miscellaneous/cb12-134.html
77 | [The Rehabilitation Research and Training Center on Disability * Statistics and Demographics: 2018 Annual Report]: https://disabilitycompendium.org/sites/default/files/user-uploads/Annual_Report_2018_Accessible_AdobeReaderFriendly.pdf
78 | [Americans with Disabilities: 2014 Report]: https://www.census.gov/content/dam/Census/library/publications/2018/demo/p70-152.pdf
79 | [WebAIM: Web Accessibility and SEO]: https://webaim.org/blog/web-accessibility-and-seo/
80 | [PopArt Studio: Inclusive Design: Making Websites Accessible to Everyone]: https://www.popwebdesign.net/popart_blog/en/2018/12/inclusive-design-making-websites-accessible-to-everyone/
--------------------------------------------------------------------------------
/security/security_policy_compliance/verified-commits.md:
--------------------------------------------------------------------------------
1 | # Github Verified Commits
2 |
3 | The identity of a person committing to a Github repository is not tied to their Github account. It is instead part of your local Git configuration which Github reads and attempts to fill in other information from what it knows about its users. For an example of this, see [pull request #64][why-verified-is-important] in the Sparkbox Standard Github repository which shows that any individual may make commits that appear to be from someone else.
4 |
5 | The solution to this is "Verified" commits. Verified commits are changes to a git repository that have been [cryptographically signed][wikipedia-digital-signature] by the committer. Github's role here is the same, it is merely reading information from the Git repository and filling in information from what it knows about it's users. The difference is that rather than relying on configuration data (such as an email address) they can verify a commit was signed by someone who has previously shared information with them. That information is called a "key" and there are actually two of them: one public and one private. This guide discusses how to generate those keys, how to use them, and how to keep them safe.
6 |
7 | ## Generating Keys
8 |
9 | [GPG Keychain][gpg-tools-website] is an easy and convenient way to generate signing keys on macOS. The first time you run it GPG Keychain will ask you to generate keys for yourself. Enter the information requested, including your full name and Sparkbox email address. Use 1Password's password generator to create a strong passphrase. Make it as long as 1Password will allow and be sure to include a few digits and symbols. You'll never be typing this in manually.
10 |
11 | ## Adding Your Public Key to Github
12 |
13 | Once you have generated your keys copy the public key by two-finger clicking on the line labeled with your name and email address and then clicking `copy`. Add this to your [Github account keys][github-account-keys] just like you would a new SSH key. You'll see a separate section on that screen for GPG keys.
14 |
15 | ### Github Email Address
16 |
17 | Now is a good opportunity to make sure Github knows about your `@heysparkbox.com` email address. Because we used this address when creating your GPG keys, Github needs to know about it to associate commits which have this address with you. Visit your [Github email settings][github-email-settings] and, if necessary, follow their instructions for adding that address. Also, make sure that it is [verified][github-verified-email]
18 |
19 | ## Configuring Git
20 |
21 | ### Adding Your Signing Key
22 |
23 | Git must be made aware of your new key and must be directed to sign all new commits by default. To do that, first return to the GPG Keychain app, highlight the line identifying your keys, and click `Details` at the top-right of the window.
24 |
25 | 
26 |
27 | Copy the `Key ID` near the middle of that new window to your clipboard. Git uses this information to locate the GPG key. To tell it how, issue the following command in a terminal window:
28 |
29 | $ git config --global user.signingkey keyid
30 |
31 | Replace `keyid` with the value you copied from GPG Keychain. Git also needs to know that you want to sign all commits. That's one more terminal command:
32 |
33 | $ git config --global commit.gpgsign true
34 |
35 | ### Setting Your Email Address
36 |
37 | Each Git commit includes your email address which Git stores in its configuration. For your commits to be verified that email address must match one of the email addresses included in your GPG key. This guide had you create your keys with your `@heysparkbox.com` address. To see if Git is configured to use that address, run this command in a terminal window:
38 |
39 | $ git config --global user.email
40 |
41 | If this prints your `@heysparkbox.com` email address you do not have to do anything. If it prints anything else, you can set it like this:
42 |
43 | $ git config --global user.email me@heysparkbox.com
44 |
45 | Replace `me` with your own name and you are set.
46 |
47 | ## macOS Keychain and Testing
48 |
49 | The final step is to setup a new Git repository to test that commit signing works as expected. In making your first commit you'll also save your passphrase to macOS Keychain so that you never need to enter the passphrase again. In a temporary folder, initialize a new Git repository:
50 |
51 | $ git init .
52 |
53 | Create a new text file in that directory and add some text to it. Commit that file to the new repository:
54 |
55 | $ git add .
56 | $ git commit -m "Enabling signed commits"
57 |
58 | A window will popup asking you to enter your GPG passphrase. Open 1Password and copy the passphrase you generated for your GPG key and paste it into this window. Before clicking `OK` check the box next to `Save in Keychain`. This will save your passphrase securely to your macOS profile and you will never need to enter your passphrase again.
59 |
60 | 
61 |
62 | Create a new repository on Github and follow their instructions on configuring your local repository to use Github. Their instructions will include steps to push to this new repository. Once that is complete you can see if our setup has worked by viewing the commit list on your new Github repository. There should be one commit, and you should see the `Verified` label on it.
63 |
64 | 
65 |
66 | Make a change to your text file and commit that change. Verify that nothing asks you to enter your passphrase. Congratulations, you're signing commits!
67 |
68 | ## Capturing Status
69 |
70 | You'll need to capture your "Verified" label on Github to submit it as verification of compliance with our security policy. If you already have a recent commit (the last week or so) in a repo on Github, take a screenshot and use that as your status. If you don't have a recent Github commit, you can use the repo below.
71 |
72 | There is a [dedicated repo](https://github.com/sparkbox/gpg-verification) for capturing the status of your verified commits. It's easy to generate a commit to screenshot by following these steps:
73 |
74 | 1. Clone the repo: `git clone git@github.com:sparkbox/gpg-verification.git`.
75 | 2. Make a [empty commit](https://git-scm.com/docs/git-commit#git-commit---allow-empty) in the repo: `git commit --allow-empty -m "$(git config --get user.name): verifying commits on $(date "+%Y-%m-%d")"`.
76 | 3. Push up your newly made commit: `git push`.
77 | 4. [Browse the repo](https://github.com/sparkbox/gpg-verification/commits/main) and take a screenshot showing your commit. Be sure to include the time and "Verified" badge.
78 |
79 | ## Github Desktop
80 |
81 | The Github Mac app does not support signed commits at the time of this writing. While that may change in the future, for now you must use Git in a terminal window to sign your commits. You may still use the app for creating, cloning, and updating repositories, but anything requiring a commit (including rebases) must be done via the command line.
82 |
83 | ## Keeping Your Key Safe
84 |
85 | As explained in the beginning, you have a _public key_ and a _private key_. Wherever this guide talks about sharing a key (specifically, with Github) it means the _public key_. As an absurd example, this key could be posted on an Interstate billboard and you would have nothing to worry about. It is designed to be shared far and wide with anyone who may want to verify your identity. The _private key_ however is altogether different. This should **never** be shared with any person or service. It should never leave the confines of your computer, except to be transferred to a new computer. Ideally this transfer happens offline, as infrequently as possible, with a trusted removable storage device. Don't hesitate to get help with this step if you are at all unsure. A compromised private key can be used to impersonate you.
86 |
87 | ## Expired Keys
88 |
89 | When a GPG key is created, an expiration date is set automatically. If you are still using the key on the date it expires, you will no longer have verified commit messages. You will need to either extend the date on your current key or generate a new key. GitHub will require you to re-add your expired key if you extend it, so we recommend that you take this opportunity to generate a new key for added security. Also leave the expired key connected to your account (rather than deleting it) as the dates on the key will match older commits. You will have to update your local `.gitconfig` file(s) to utilize the new signing key. [Check out the Github documentation on expired keys for more information.][github-expired-gpg].
90 |
91 | [why-verified-is-important]: https://github.com/sparkbox/standard/pull/64
92 | [gpg-tools-website]: https://gpgtools.org/
93 | [github-account-keys]: https://github.com/settings/keys
94 | [wikipedia-digital-signature]: https://en.wikipedia.org/wiki/Digital_signature
95 | [github-email-settings]: https://github.com/settings/emails
96 | [github-verified-email]: https://help.github.com/articles/verifying-your-email-address/
97 | [github-expired-gpg]: https://docs.github.com/en/github/authenticating-to-github/updating-an-expired-gpg-key
98 |
--------------------------------------------------------------------------------