We build digital experiences designed around the needs of our constituents. We work to make these tools beautiful, welcoming, and highly useful.

Getting started is where you’ll find general onboarding/high-level info about our team, the technologies we use, and how we work together.

Standards and best practices ensure that our code and workflows are consistent across the team.

Guides is a collection of how-tos and references for the technologies we work with. These should not project-specific.

Projects is where general documentation for a specific project can be found (project-specific technical documentation is better suited for the project README). This section is primarily the domain of product managers. Private information is kept in Google Docs that are linked to from here. External resources is where to find links to useful information and tools.“Learning resources” are things like tutorials and guides. “Reference links” tend towards specs, references, and tools.

Can I become who I want to be?

That's a tough question but thankfully, our team is on it. Please bear with us while we're investigating.

Have you had a chance to answer the previous question?

Yes, after a few months we finally found the answer. Sadly, Mike is on vacations right now so I'm afraid we are not able to provide the answer at this point.

Daily

Slack daily standup

Participants: Entire digital team

• Accomplishments or discoveries from the previous day

• Priorities for the day

• Any roadblocks, questions, or hang-ups?

Weekly

Product development sync

Monday mornings, required

Participants: Developers, Product Managers, Chief Digital Officer, Quality Assurance, UX, etc.

Format: Talk through accomplishment(s) last week, priority(ies) this week, flags

Digital staff meeting

Thursday morning, required

Participants: All digital team members plus invited guests as appropriate

Format: Each team member shares a “brag,” any “flags”, and a “learn” with the rest of the team.

#Demo

Friday afternoons, optional but encouraged

Participants: Any/all

Format: Team members may demo something they’ve accomplished during the week. Prompt on what you’ll demo is made by Slack on Thursday afternoon.

Project team meetings

Participants: Anyone who is a part of the identifying project team. Will typically at least include a product manager and developer from our folks.

Format: Determined by project team, but typically includes a review of the kanban project board for part of it.

Conduct

Engineers on the Digital team will treat each other with kindness and respect. We will support each other in learning new things, honing our craft, and building great software for the people of Boston. We do not look down on each other for any reason, including background, area of expertise, or identity.

Values

We value iterative development and continuous deployment. We recognize that delivering changes in small batches means that we go faster with a lower risk of breaking something.

We value communication and shared knowledge. While we may work on separate areas of Digital’s portfolio, we develop and document so that others can step into our shoes as needed. We visualize work to better communicate and hold ourselves accountable. We celebrate each other’s wins.

We value transparency. We are part of a public institution working for the people of Boston, and we are accountable to that. We make our roadmap, work in progress, and results public to all.

We value continuous improvement. We hold retrospectives and experiment with our process in order to learn and work together more effectively.

We value consistency in user experience, and in code.

We value automation and defaults. Out-of-the-box solutions are easier to maintain and teach than custom ones.

We value security and privacy. We are stewards of the public’s data and take that responsibility seriously. We will not build software that can be used for abuse or harassment.

We value maintainability. Because projects move in and out of active development, we need good test coverage to guard against accidental breakages and easy development setup so that others can work on the code.

We value monitoring. We use services to report on exceptions and add alerts so that we know when our services are down. We record analytics for insight into how constituents use our products.

We value diversity of background, experience, and identity. Bringing people with different perspectives together to solve a problem leads to a stronger, more inclusive solution.

Process

We run fairly process-lite, not because we reject process in general, we just only want to adopt what’s useful for doing the best work. The practices we have adopted are described in Best practices.

Prioritization

The overall prioritization of projects is the responsibility of the Chief Digital Officer, and should be the overall guide for deciding which new work to “pull.” (Glossary: What is a Pull System?) Engineers have some leeway in this area to try and minimize switching cost between projects.

Prioritization of a project’s features is the responsibility of the product manager for that project. Work for a project should generally be pulled in priority order. Use good judgement to pull other work in exceptional cases (for example, someone you need to work with has free cycles).

It is the responsibility of engineering to provide honest information and be a good collaborator in the prioritization process. “Responsibility” for the CDO and PM is not “sole responsibility.” Engineering is expected to be a participant in the prioritization process.

Learn more about using a Kanban board to track prioritization within a project.

Browsers We Support

These are browsers we support for development and quality assurance testing. Note: These are based on the City's top browser versions tracked via City's analytics traffic. These will be revisited quarterly by the product development team and quality assurance lead.

• Google Chrome 68 and higher

• Safari 11 and higher

• Internet Explorer 11 and higher

• Firefox 61 and higher

• Edge 17 and higher

Testing Breakpoints

• 320

• 840

• 1280

Adding images/svgs

• SVGs - please remove all "id" attribute in the svg. It is always the same and creates a BIG error when the browser sees the same id for so many images/svgs

• Images: Always add a title or alt tag to an image. But, make it meaningful. See example below.

• Development: https://access-boston-dev.digital-staging.boston.gov/

DO:
title/alt - "Demolition Delay application: 50 Landseer Street, West Roxbury"

Don't:
title/alt - "Image and/or photo of Demolition Delay application: 50 Landseer Street, West Roxbury" 

Editing/Adding Tables

• Adding Tables: Always make sure you add a table title and/or summary and/or caption

• Test: https://access-boston-test.digital-staging.boston.gov/

• Development: https://access-boston-dev.digital-staging.boston.gov/

Adding nofollow and/or hiding pages

• Production: https://access.boston.gov

• Test: https://access-boston-test.digital-staging.boston.gov/

• Development: https://access-boston-dev.digital-staging.boston.gov/

Adding iFrames

• Production: https://access.boston.gov

• Test: https://access-boston-test.digital-staging.boston.gov/

• Development: https://access-boston-dev.digital-staging.boston.gov/

Content Editor Guide

• The links with the same name should have the same href values when on the same page

• Using classes on html elements you want to hide from screen but allow screen readers to access:

  Copy

  sr-only sr-only-focusable

• Development: https://access-boston-dev.digital-staging.boston.gov/

Articles

Tools and Other Resources

• ANDI

• VPAT

• A Complete Guide To Accessible Front-End Components

• Intro to Web Accessibility

• Focus and Focus Styles

• More about Keyboard :hover, :focus, and :active pseudo-classes

• https://learn-the-web.algonquindesign.ca/topics/html-semantics-cheat-sheet/

• https://learn-the-web.algonquindesign.ca/topics/accessibility-cheat-sheet/

• https://www.deque.com/blog/auditing-design-systems-for-accessibility/

• https://www.w3.org/WAI/WCAG21/quickref/

• https://storybook.js.org/blog/accessibility-testing-with-storybook/

What to look for

• Keyboard focus on focusable elements

• Tab order

• Label tags

• Title attributes

Keyboard access

• All "clickable" elements must be keyboard accessible

• Likewise all hover/focusable elements must have alternate keyboard focus matching the mouse hover

Colors and fonts

• Text colors should be tested for contrast. Make sure there is good color contrast between the text and the background

• A recommended minimum font size is 16 px. Use bold to add emphasis rather than italics or UPPERCASE, but use it sparingly!

Images vs background images

• Use background images only if necessary

• All images must have an alt tag

• Actual images must be use if it gives content more meaning or is the only content.

HTML Structure

• Content will be read from left to right, therefore html should be written out the way the keyboard will tab through content

• Input elements should have labels. They can hidden if not part of the design, but needs to be there for screen readers

• All HTML should have proper aria attributes

• Lists should have the proper role attribute

Titles, captions, and summaries

• Iframes should always have a title to explain the content of the iframe

• Tables must have summaries explaining the content of the table and Captions foe really large tables.

• Images should always have meaningful titles for screen readers to read

• Anchor tags <a>...</a> should always have a title

Links and buttons

• A link should always be a link and not a placeholder

• Buttons

Miscellaneous

See boston.gov/digital for a lot of historical write ups on this work.

Write up on accessibility and text to speech completed for Jeniffer Vivar Wong/Office of Language and Communications Access on 4/5/21: https://docs.google.com/document/d/1aa9wCaG3AzPsh6pPC-padNOv4YgazwyUs2VkWglvSHA/edit

Potential ideas we found/brainstormed while writing this:

Tools/things Reilly found via Googling:

• https://chrome.google.com/webstore/detail/talkie-text-to-speech-man/enfbcfmmdpdminapkflljhbfeejjhjjk?hl=en

• https://ai.googleblog.com/2019/09/large-scale-multilingual-speech.html

• https://github.com/Tomiinek/Multilingual_Text_to_Speech

• https://www.techradar.com/best/best-text-to-speech-software

Things Digital could consider:

• Bringing back the ‘accessibility’ header. Can’t remember if it ever got built and we just turned it off but there are designs for it

• Drupal modules for text to speech - would need devs to advise

  • Would want to do some market research with other govs or places before implementing

  • Lots of reference to Google cloud text to speech or Amazon Polly - unsure if this would be included in free license or we’d need to pay

• General Assembly project for general user experience/desire of this or the City spending some money and hiring a consultant for this or a USDR volunteer

Testing

1. Install ANDI: https://www.ssa.gov/accessibility/andi/help/howtouse.html

Adding Tables

• Add "summary" to table tag. A summary conveys information about the organization of the data in a table and helps users navigate it.

• Add "scope" to tables with headers. The scope attribute can be set to row or col to denote that a header applies to the entire row or column, respectively.

• Add "captions". A caption functions like a heading for a table. Most screen readers announce the content of captions.

<table summary="some summary here">
  <caption>Concerts</caption>
  <tr>
    <td></td>
    <th scope="col">Date</th>
    <th scope="col">Event</th>
    <th scope="col">Venue</th>
  </tr>
  <tr>
    <th scope="row">09:00 - 11:00</th>
    <td>12 Feb</td>
    <td>Waltz with Strauss</td>
    <td>Main Hall</td>
  </tr>
  […]
</table>

Adding SVGs

• If it is used as an img, must add title attribute to it.

• If svg is use as a button, must add a tabindex attribute

<label for="s-tr" title="Search" class="nv-h-l-a nv-h-l-a--k nv-h-l-a-ic" id="searchIcon" tabindex="0">
   <svg id="Layer_2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 41"><title>Search</title>
     <path class="nv-h-l-a-i" d="M24.2.6C15.8.6 9 7.4 9 15.8c0 3.7 1.4 7.2 3.6 9.8L1.2 37c-.8.8-.8 2 0 2.8.4.4.9.6 1.4.6s1-.2 1.4-.6l11.5-11.5C18 30 21 31 24.2 31c8.4 0 15.2-6.8 15.2-15.2C39.4 7.4 32.6.6 24.2.6zm0 26.5c-6.2 0-11.2-5-11.2-11.2S18 4.6 24.2 4.6s11.2 5 11.2 11.2-5 11.3-11.2 11.3z"></path>
   </svg>
</label>

iFrames

• iFrames needs to have a title attribute

images vs background images

• Images must have an alt attribute

• Images can also have a title attribute

• If an image gives a better understanding or context to a content, that images should not be a background image but an actual image.

Summary

Developers can emulate links with other elements, such as <div> or <span> elements and JavaScript click listeners. But, these kinds of emulated links need care. Developers wishing to emulate links must include the following:

• Add tabindex=”0” so that the link becomes keyboard focusable

• Add role=”link” so that assistive technology recognizes the element as a link

• Add the styling cursor: pointer so that mouse users will recognize the element as a link.

• Same applies to html elements used as buttons instead of the actual <button> or <input> element.

<!-- Link example -->
<span role=”link” tabindex=”0” style=”cursor:pointer;text-decoration:underline;color:blue;”>This is an emulated link</span>

<a href="https://boston.gov">Click Here</a>

<a class="subnav-anchor" id="stay-connected" data-text="Stay Connected" href="javascript:void(0)" title="This is an anchor"></a>

<!-- Button example -->
<div id="saveChanges" tabindex="0" role="button" aria-pressed="false">Save</div>

<button id="saveChanges">Save</button>

For example, the markup for an accessible emulated link might look like the following:

To avoid needing to implement the above, developers should prefer to use the <a> tag instead.

Focus vs Focus-within

What is css :focus and :focus-within? How do you know when to use them? Read more about how to use :focus here.

Note: If using role="button" instead of the semantic <button> or <input type="button"> elements, you will need to make the element focusable and have to define event handlers for click and keydown events, including the Enter and Space keys, in order to process the user's input. See the official WAI-ARIA example code.

Semantic HTML5

Remember that most browser will automatically validate correctly written HTML for you. Keep them simple with less layers of html tags wrapping them endlessly.

Visit them at: https://iteratorstesting.com/services/accessibility-testing

Trusted Tester Tests: The Section 508 Trusted Tester program groups the WCAG requirements into related groupings that can be tested (and developed) at the same time. With the help of Iterators the VPAT documentation for boston.gov was created. You can read the documentation here.

Test #4) Keyboard and Focus

Purpose:

• Many different types of users decide to use a keyboard to navigate a web page. Some

  examples are screen reader users that will tab through an interface. Other users have

  motor impairments and must control a computer through a switch (such as puffing into a

  straw, etc).

• People that use a mouse can quickly navigate a website. Additional design features are

  needed to allow the same level of access to people that use a keyboard to navigate a user

  interface.

Requirements:

1) Users should be able to access all functionality by using only the keyboard.

a. First, use a mouse to identify all functionality (buttons, links, etc)

b. Second, try to utilize all of the same functions using the keyboard, mainly using the tab and enter keys.

c. This also applies if popup features are implemented, such as an informational dialog, etc.

2) Tabbing through a user interface should occur in a logical order that matches the visual pattern on the screen, such as left to right, top to bottom.

3) Tabbing through a user interface should cycle completely through the interface and not be “trapped” in a cycle.

4) Focus is visible when using a keyboard

a. Sometimes a blue border is used to show the currently active element when using a keyboard. This should be easily visible with all elements.

b. Sometimes using a mouse will also highlight an element or reveal some information. These two methods should be compatible with each other.

c. The focus should always be visible and there should not be any invisible elements when using a keyboard.

Test #9) Repetitive Content

Purpose:

It is easy to skip over content using a mouse. However, keyboard navigation users must traverse many repetitive elements such as menus.

Requirements:

1) Identify all areas of a page with repetitive content.

a. A typical example is the navigation menu at the top of web page.

b. Some web pages have multiple sections of different content, such as “news”, “events”, etc. If there are many sections, then a user might like to skip the “news” section and jump to the next section without traverse all of the elements in that section.

2) Provide a “Skip” link, such as “Skip to Main Content” for each of these repetitive areas. This skip link is typically only visible when a user is using a keyboard to navigate through a web page.

Test #6) Links & Buttons

Purpose:

• Keyboard users should be able to determine the context for any link or button. Often

  users determine the context by visually examining nearby text or graphics.

• Additionally, some links and buttons cause a change in content on a website which is

  visually observable and also needs to be accessible to keyboard users.

Requirements:

• The major requirement is that accessible and unique descriptions are available for each

  link and button. For example, a set of links to news events might be labeled as “Read

  More…”. However, the user may not be able to determine which news event is

  associated with each link. The link may still be labelled as “Read More…” as long as

  there is also accessible text that provides more description, such as “Read More about the

  City of Boston”.

• Any new content that becomes visible with a link or button should be identified with

  accessible text before the user clicks on the link or button. An example of this is a

  “Learn More…” button that causes a new modal dialog to be shown. Also, the keyboard

  navigation should move to the new content.

Environments

• Production: https://boston.gov

• Test: https://d8-stg.boston.gov/

• Development: https://d8-dev.boston.gov/, https://d8-uat.boston.gov/, https://d8-dev2.boston.gov/, https://d8-ci.boston.gov/

Slack

• Our main channel is #digital_team.

• The #digital_builds channel reports build and deployment status.

• The #digital_monitoring channel reports alerts and exceptions.

• Most projects have their own public channel to keep all relevant and/or interested parties in the loop on active project work or to follow along with questions/answers that would benefit at all. Feel free to follow projects that you may not be actively working on.

• There are some 'culture building' channels. Feel free to add yourself to whichever of these channels.

*Note: This is largely used by Digital and Analytics within DoIT. Most others use GChat.

Listservs

The team communicates internally and externally via Google Group listservs:

• digital@boston.gov (entire team) - James Duffy is typically first on deck to respond to these.

• feedback@boston.gov (limited folks on Digital) - James Duffy is typically first on deck to respond to these.

• digital-dev@boston.gov (developers, product managers)

• webmaster@cityofboston.gov (developers, product managers)

Contributing to Boston.gov

:+1::tada: Thank you for being interested in contributing to Boston.gov! :tada::+1:

This is a guideline for contributing to the development of Boston.gov. We're open to improvements, so feel free to send a PR for this document, or create an issue.

Jump right in

• Report issues on Boston.gov

• Suggest new features

• Contribute to development

Reporting bugs

If you need to submit a bug report for Boston.gov, please follow these guidelines. This will help us and the community better understand your report, reproduce the bug, and find related issues.

Before you submit a bug

• Verify that you are able to reproduce it repeatedly. Try multiple browsers, devices, etc. Also, try clearing your cache.

• Perform a quick search of our existing issues to see if it has been logged previously.

Submit a bug

• Use a clear and descriptive title when creating your issue.

• Include a bulleted list of steps to reproduce your issue.

• Include the URL of the page that you're seeing the issue on.

• Include screenshots if possible. Bonus points if you include an animated GIF of the issue.

• Include details about your browser (which one, what version, using ad blockers?).

• When filing your issue, assume that the recipient knows nothing about what you're talking about. There is no such thing as too many details when filing your issue.

Bug report template

## Basic details

URL: [URL]

## Steps to reproduce

1. [FIRST]
2. [SECOND]
3. [THIRD]

## What I think should happen

[Describe your expected behavior here]

## What did happen

[Describe the actual behavior here]

## Browser details

Browser: [Enter browser]
Version: [Enter version]
Ad blocker: [Ad blocker?]

[SCREENSHOT]

Suggest new features

Have an idea for Boston.gov? If so, create an issue. Prior to submitting your feature request, please do a basic search of existing issues to see if it's already been suggested.

Feature template

## User story

[Don't write:
  "As a <type of user>, I want <some goal> so that <some reason>."]

[Tell us a story instead:
  "I like knowing what major construction projects are planned for my neighborhood. It makes me good to review
  those project documents and share my opinion on them at any public hearings. It's a hassle to constantly 
  check the website, though. Is there any way I can automatically get an email when something is happening
  within a certain distance from my apartment?]

## Acceptance criteria

1. [FIRST]
2. [SECOND]
3. [THIRD]

[Example:
1. Be able to sign up for an email notification.
2. Receive an email notification with proposed construction projects and associated hearings.
3. Be able to indicate an intent to attend a specific hearing.]

## Good examples to share

[Add links, screenshots, mockups, or any other example of where you've seen someone do what you're requesting
_well_. Add a brief description of what you like and/or dislike about it.]

Contribute to development

To contribute to the development of Boston.gov, you'll need to get a development environment up and running. This section will get you started.

Contributors should first review our [[Development Standards]].

Our process resembles a Gitflow Workflow with the following specifics:

• The master branch is always ready for deployment.

• All development is performed against a develop branch.

• Before release, develop is deployed to our staging environment and tested. It is then merged into master and master is deployed to production.

Project setup

Each contributor should fork the primary Boston.gov repo. All developers should then checkout a local copy of the develop branch to begin work.

For any work, pull requests must be created for individual tasks and submitted for review. Before submitting a pull request, be sure to sync the local branch with the upstream primary branch.

Pull requests should be submitted from the forked repo to the develop branch of the primary repo. Make sure to give your pull request a clear and descriptive title and use the template below.

Pull request template

## Changes

 * [First change]
 * [Second change]
 * [Third change]

This PR references #[GitHub issue number]

Product managers should work with stakeholders and the project team to determine what we'd like to track/count as success metrics.

Product managers are first on deck to enter tags in tag manager to track this information. Developers are a back up for this.

Ideas for potential metrics include:

• Standard high level google analytics, such as page views, unique page views, browser, network, device, time on page, etc.

• Conversions, such as sign ups, participation in events (in-person or online), results in City services (i.e. less towing)

• Completion rates, i.e. if they visited a page that they needed to interact with something or get through a task did the 'page visits' match the 'completed rates'

• Numbers of things, such as orders,

• Savings or revenue: time, money, etc.

Drupal_Tag/2023_02_03

DIG-1033 - Price Filter Updates

• This enhancement updates the price filter on the Metro Listing page so users have the ability to enter minimum and maximum prices to filter a price range appropriate to the listing type(rental or sales) they are searching

DIG-1043 - Show either rental units or for sale homes, not both

• This enhancement separates rentals and sale properties in the search results so users are not confused by the listing type they are viewing

DIG-1714 - Metrolist price filters don't work on Sale properties

• This enhancement shows the user sale properties when they are using the price filters on the Metro Listing page

Drupal_Tag/2023_01_26

DIG-1770- Metrolist Listing Form Error

• Code was rolled back to the previous version after the listing form was throwing an error. Cause and Solution will be investigated for permenant fix

Patterns_Tags/2023_01_26

DIG-1659 - UI change to Boston.gov contact form

• This adds email validation to the contact forms to avoid postmark errors

Drupal_Tags/2023_01_25

DIG-1679- Adjust style for document link button in "three column w/ image" component

• Update the styling of document link on a three column image component so internal and external button links match

DIG-1720 -PDF Generation may fail if multiple requests occur simultaneously

• This fix allows endpoint folders to accept both upper and lower case fiscal year names so the form accept process is not blocked.

Registry_Tags/2023_01_24

DIG-1564- Add email validation to marriage intention form

• This adds email validation to the marriage intention form. A user must enter matching emails before submitting the intention form. If the emails do not match the user will get an onscreen error message. This will ensure we do not receive postmark errors due to incorrect/incomplete email addresses.

DIG-807- Add email validation to registry applications

• This adds email validation to the birth, death and marriage certificate request forms. A user must enter matching emails before submitting any of these request forms. If the emails do not match the user will get an onscreen error message. This will ensure we do not receive postmark errors due to incorrect/incomplete email addresses.

Drupal_Tags/2023_01_17

Digital Team

DIG-1164 Address Barcode for abatement application through assessing online

• This update added code that writes a PDF and adds a barcode to the downloadable exemption information section of the abatement application

DIG-1653 Bug with last name in 'grid of quotes' component

• This bug fixes the name display on the grid of quotes feature in Drupal. When editors add a persons full name to grid of quotes it will display correctly on Boston.gov

DIG-1687 'Add to calendar' button not working on 'events"

• This bug fixes the error where the Add to Calendar button on the events page was not working properly. When users clicked this button to add the event to their calendar nothing happened. When users click this button now it gives them the option to add the event to their preferred electronic calendar

DIG-1712 - Update Street Numbers on Forms

• This fix updates the way addresses appear across assessing forms.

Metrolist

DIG-1561 Fix Styling of Metrolist Grid of Cards

• This fix updates the Grid of Cards styling on the Metrolist page to match everywhere else on the site

DIG-1584 Change "Calculate" to estimate on unit details screen

• This update changes the text on the Metrolist unit details screen from calculate your eligibility to estimate your eligibility in the Eligibility Section

Patterns_Tag/2023_01_13

DIG-1652 Styling of bullets needs to be adjusted

• This fixes a bug that was introduced when the bullet styling was updated to make them display better in the new tables, the bullets were being displayed in the middle of a multi-line sentence instead of in front of the first line. When bullets are used in a list the user will see the bullet positioned in front of the first sentence in a list

Digital_Tag/2023_01_05

DIG-1509 Group Management Search Order

• The search order in the Group Management tool on Access Boston Portal was enhanced so users see their search results in alphabetical order

Digital_Tags/2022_12_23

DIG-1223 Error message in search of Permit Finder website

• This fixes a bug where users where seeing an 400 error when using the permit finder website

Drupal_Tags/2022_12_23

Digital Team

DIG-1545 - Adjust feedback link in navigation for pages where feedback form appears

• This adds functionality to the feedback link seen the on top of Boston.gov pages. If a Boston.gov page has the newly created feedback embedded when the feedback link is clicked the user will navigate directly to the new feedback form at the bottom of the page

• If there is no feedback form embedded on the page, when the feedback link is clicked the user will see a contact form that submits an email to 311supervisors@boston.gov

DIG-1307 - Add updated styling to tables on Boston.gov

• This updates all the tables on Boston.gov to match the newly designed tables created for the Elections results. These new designs are for both desktop and mobile. These updates were created to align with our commitment to design and brand consistency on Boston.gov

Metrolist

DIG-1547 Make Availability Info Page Required

• Removes the check box option on the “Select Building” Page of the listing form that allows the users to skip the “Availability Info” page. This step will now be required in the submission process on the Metrolist Listing Form

Drupal_Tags/2022-12-14&15

Metrolist

DIG-1047 Open Project Pages in New Tab

• Fixes a navigation issue for users that want to open a project page from the Build In Boston map. When clicking on a project from the map the project page will open in a new tab allowing users the ability to toggle between the map and project tabs they are viewing, and close the project pages without closing the map.

Digtial Team

DIG-1591 - Dupal Updates

• Routine maintenance and code release cycle for boston.gov

Drupal_Tags/2022-12-08

Digital Team

DIG-1463 Create Boston.gov feedback form

• Enhancement in Drupal to create a feedback form that editors have to the ability to add to the bottom of any page on Boston.gov

• Feedback form works on both desktop and mobile

• The feedback form has the following features:

  • Yes/No check boxes for user experience - Required field

  • A comment text box for users to share their experience in paragraph form

  DIG-1544 'Notes' error when viewing feedback form submissions

• Fixes a bug where users were seeing an error when they clicked the notes option on individual Drupal pages

Metrolist

DIG-777 Listing Form: Availability Info Screen

The following updates were made to the Availability Screen on the Metrolist form:

• Set default time in Deadline Time field to 11:59PM

• Add the “Remove Posting Date” date field so users can add a date to indicate when a posting should be removed so applications cannot be submitted after that date

• Updated the name of the “When would you like this posted to Metrolist“ field to “Available On”

DIG-838 Equitable Treatment agreement

Three changes to the notification requiring equitable treatment and non-discriminatory practices agreement:

1. Moved to bottom of page, just above submit button

2. Added "I agree" checkbox as part of notification

3. Disabled "Submit" button until "I agree" has been checked

DIG-1040 Fix Pagination icons to show displayed page

• This updates the Metrolist Listing form so the user sees the pagination icon highlighted to indicate which page they are currently on

Digital_Tags/2022-12-02

DIG-1024 View Only Group Management

• Enhancement to the Group Management Tool on Access Boston Portal that allows users to search and view employees/contractors list of security groups in view only mode

• Users with the following security group SG_AB_GROUPMGMT_SERVICEDESKVIEWONLY will see the Group Management link on their Access Portal page

• Users will have the ability to search on users by name or ID

• Once the correct user is found and selected their security groups will be displayed in view only mode. No edits can be made to the security groups

Drupal_Tags/2022-12-01

DIG-878 'Grid of quotes' component image upload issues

• This fix allows users to upload an image by easily clicking the “media add page” in the "Grid of Quotes" component, instead of forcing them to add the media then searching to to find it so it displays

• This also fixes the display itself so that the image can been seen instead of displaying the file name

DIG-1362 Display unofficial results in the same order as the ballot

• This fix allows user to see the unofficial election results data displayed in the same order as it is listed on the official election ballot when it appears on the unofficial elections results page

• The election data order should also display in the same order as the ballot in the filtered drop down for searching

DIG-1393 Add field to Drupal to allow election editors / admins to edit disclaimer

• This fix gives election editors or admins the ability to update the disclaimer message on the Elections Results page

• The editor will see a new field to add or update a disclaimer message in Drupal

DIG-1435 Error on elections file upload crashes upload form

• Fixes an issue to prevent upload crashes when an elections file is uploaded

• To fix this issue the following solutions were implemented:

  • Made the form more tolerant to missing or orphaned data in the history object which is dynamically stored in the node_elections config settings.

  • Added a clear history button to the form so an admin can manage the history

  • Added logging into the history so that clearing and deleting history is recorded

DIG-1511: Maintenance Updates

• Routine contributed module updates for Drupal

DIG- 1519 Content authors / editors unable to see drafts of unpublished content

• Fixes a bug where editors were unable to see their Draft Drupal pages, When a user saves a “draft” for a new content type, they get a “temporarily unavailable” message

• After an update in Drupal the DateTime module seemed to be less tolerant to formatting a date, the code was updated so that the published date will only be formatted if the node has been published

Digital_Tags/2022-11-09

DIG-62 Unmask a Password - Sign in Screen Access Boston Portal

• Added a show password feature to the sign in screen on Access Boston Portal. This allows users to click on the word 'Show' to unmask the password they are typing to make sure it is correct

NOTE: This code was developed by the digital team but released by the IAM team because this page lives on their servers

DIG-1155 Unmask a password - Change Password Screen

• Added a show password feature to the Change Password screen on Access Boston Portal. This allows users to click on the word 'Show' to unmask the password they are typing to make sure it is correct

• This screen is also used in the create password process for new users/employees

DIG-1156 - Unmask Password - Forgot Password Screen

• Added a show password feature to the Forgot Password screen on Access Boston Portal. This allows users to click on the word 'Show' to unmask the password they are typing to make sure it is correct

Drupal _Tags/2022-11-03

• DIG- 1363 - Add disclaimer message to top of unofficial election results

Added a disclaimer message to the top of our unofficial election results election card to clarify the order that results appear for users.

• DIG -1374 - Add error validation in election uploads

This addresses an issue with uploading xml files in our new Election Results section in Drupal. It adds further error validation for users uploading problematic files.

Patterns_Tags/2022-11-03

• DIG- 1343-Adjust styling of tables on mobile

Adjusted the styling of our tables when viewing them on mobile in our patterns library. This change eliminates adding an extra border at the bottom of each cell, and instead adds the bottom border below groups of data on mobile.

Drupal_Tags/2022-11-01

DIG - 1333 Adjust text in filtered dropdown for primary elections

• Capitalized "rep" and "dem" party descriptors in the race selection dropdown

Drupal_Tags/2022-10-28

Unofficial elections results are mobile-friendly on Boston.gov

Epic: DIG- 943

Background: The unofficial election results website gets updated with new data each election that reflects the current race. The data for the current page is currently being iframed into a website on Boston.gov. The data from the iframe is coming from the old cityofboston.gov website. It does not have City of Boston branding and it isn’t mobile-friendly.

Goal: Make unofficial election results mobile-friendly on Boston.gov

UI Design

Mobile Version

Desktop Version

Related Tickets

DIG- 1004 Importing Elections Data into Drupal

• Created a new content type packaged in the module node_elections allowing the elections dept to upload elections results into a drupal page

• Created an import page for the elections department to import election results file that will appear on the elections website

• Created an import process where election results file contents are loaded into the new content type to updated the elections results site

DIG- 1093 Create display pages for unofficial results

• Front end development work to create display pages for election results that align with approved UI designs and our patterns library

Drupal_Tags/2022-10-17

DIG-1206 Drupal Security update 9.4.8

Patterns/2022-10-07

DIG-854 Update patterns library to Node 18

Drupal_Tags/2022-09-23

DIG-1060 - Fixes a bug where the postmark contact form was not automatically adding the correct email address in the CC field so Boston City Workers could click reply all without having to cut and paste the email address into the To field. This fix allows users to see the email address in the To field after click reply or reply all.

Drupal_Tags/2022-09-21

DIG-881 - This updates the my neighborhood look up tool by swapping out the summer links for the winter links.

DIG-2021 -Routine scheduled updates to Drupal contributed modules

AWS AMI Update/2022-09-21

• Weekly Maintenance that updates both PROD and the REPO

Registry_Tags/2022-09-20

DIG-1002 Error message in Registry suite of applications

• Fixes issue where users are getting a 400 error in Registry Suite of Applications

• Issue was due to a malformed cookie

Drupal_Tags/2022-09-20

DIG-1009 Internal links considered "external" causes WSD on older pages

• Fixes issue where Cabinet page links were broken

• Updated code to ignore hard coded part of the URL and read the remainder of the path to display the correct page

Drupal_Tags/2022-09-19

DIG-993 Contact forms on Boston.gov failing to send

• Fixes issue where users were unable to send emails via the "mail to" links on Boston.gov

• A class was not registered for the email sending process via postmark

DIG-872 Add 'last updated' to 'updated' date in 'posts'

• This adds "Last Updated" before dates on a published Boston.gov page so users know when Boston.gov page has last been updated

DIG-949 Verify pages to be scanned by Percy

• Added a good selection of pages from Boston.gov for Percy testing

DIG-1005 Internal links considered "external" causes WSD on older pages

• Fixes issue where a URL link cannot resolve because drupal considers is external

• Fix is to check if the link is external before trying to load the associated node

BoardsandCommissions_Tag/2022-09-16

DIG-905 Apply button error in 'commission summary' component

• Fixes a 400 error users see when they click the Apply Online button on a Boards and Commission page

• Issue was due to a malformed cookie

Drupal_Tags/2022-09-16

DIG-67 -Caching issue displaying incorrect breadcrumbs

• This fixed an issue where the breadcrumbs on the top of a boston.gov page was not consistent with user navigation

• The solution is to specify that the breadcrumb block be cached per url and not per content type

• The breadcrumbs now appear consistent to the users navigation path

DIG-831 (metrolist)- Clarify "Minimum income" is annual income

• Added a tooltip to the “Minimum Income” field explaining that the amount entered in this field should be annual income

DIG -925 (metrolist)- Email Language Errors

• Updated confirmation email with correct language for the user

DIG-989 - Fix subdomain redirect in configuration for rentsmart.boston.gov

• Updated our config file to point the rentsmart.boston.gov redirect to www.boston.gov/rentsmart

Drupal_Tags/2022-09-15

DIG-31 Custom 500 Error

• This will activate the 500 error page on Boston.gov.

• When a user gets a 500 error they will see the following:

Text: Sorry! Looks like something went wrong on our end. We're currently working to fix the issue. You can try re-loading the page in a few minutes, or email feedback@boston.gov with any questions or concerns.

DIG-853 Re-integrates Percy

• This work re-enables Percy on Boston.gov

• Percy will assist in automated testing by comparing screenshots to ensure new code does not break anything on Boston.gov

• Percy tests must pass in order to merge new PRs

DIG-876 Resolves internal link WSD

• This fixes a validation error for broken internal links in components

• If a user enters an internal URL the page will resolve itself and navigate to the correct URL when saved

• When users try to save a draft page with a broken internal link they will get an error message.

Drupal_Tags/2022-09-07

DIG-542(Metrolist) Calendar events do not show physical location

• This will update calendar events to pull in the physical address of the event so users see the correct address on the site

• This update will also accommodate events that will be held virtually - users will see language on screen saying the event will be virtual

DIG-738(Metrolist) Stop re-submission of form once submitted

• Update to add language to the Metrolist listing form informing users the unique link they receive to submit a listing should only be used once. The following language has been added to these screen/emails

  • Listing Form Request - Important: If you need to submit listings in multiple properties, please request a new form for each one.

  • Email communication -Important: Do not reuse link. If you need to submit listings for additional properties, please request a new form

  • Listing form request on screen notification- Important: If you need to submit multiple listings, please request a new form for each building.

DIG-776(Metrolist) Submission Confirmation Email

• Send a "Submission successfully completed" email notice to the contact associated with the listing when a submission is completed

DIG-775(Metrolist) Update Admin email alert

• Update the Admin email recipient list, add meaningful info, and include a link to the Salesforce Development. Email will contain:

  Submitted on: [Date/time stamp] Submitted By: [Listing Contact Name] Listing Contact Company: [Listing Contact Company] Contact Email: [Listing Contact Email] Contact Phone: [Listing Contact Phone]

  Property Name: [Development Name] Property Address: [Street, City, Zip]

DIG-781(Metrolist) Apply Button on listings gets 404 Not Found

• Fixed bug where Apply button on MetroList Listing page was getting a 404 page error

DIG-809(Metrolist) Issues accessing Metrolist from external devices

• Fixed bug where Metrolist search page was not loading on some devices

• In the listing date code \T was being read as timezone updating this to \\T fixed the issue

DIG-433 (Metrolist)Telephone number (&date) format on metrolist_listing webform

• Fixed bug where user sees a formatting error after entering a phone number

DIG-824 Update BOS311 API for Chinese translation

• Chinese translation was not appearing in BOS:311 App

• API was updated to send correct language code so alerts show in Simplified Chinese

DIG- 865 Fix styling of events component in how-to page

• Fixed styling on events and notices component so events boxes are not pushed to right of the screen and appear centered on the site

Drupal_Tags/2022-8-24

DIG-317: How-to pages broken components

• Fix styling issues with How To content type from patterns library

DIG-318: Node landing page Full

• Minor edit to the wrapper around the main items

DIG-319: Node Listing Page

• Took out unnecessary code to make sure listing pages look correct

DIG-438: Add email re-verification field.

• Added validation email field to Postmark contact form so users have to validate their email before submitting a question etc.

DIG-757: Event calendar bleeding into the bottom module

• Fixed a bug where the calendar button was bleeding onto the components section in events, this has been aligned

DIG-733: Features sidebar svg

• Fix icon svg files appearing too large in the features section on the ArtsBoston Calendar. They are now appearing at normal size

DIG-781: Apply button on listings gets 404

• Fix the apply button on Metrolist listing so when clicked user can apply to any listing

AccessBoston_Tags/2022-08-18

DIG-65 - Group Management URL Security Fix

• Fixes the following security issue of allowing users to access group management via copying a URL directly into the browser

• Users that do not have access to group management will be directed back to the Access Boston Portal screen

Adding Images

• When adding images to content, must add caption and/or title and/or alt tags. This is especially important because screen readers reads them.

• The editor we are using "ckeditor" provides at least one field to enter either a caption, title, or alt tags. If all three fields are provided please enter content for all three fields.

• Please see the "How guide" section on the best ways to add and edit an image.

Adding Tables

• Tables summaries must be added to each table created. Editors can use "ckeditor" to add summaries to each table. The summary must explain exactly what the table content is about.

• See the "How to guide" section to learn more about adding table summaries to tables

Adding Buttons and Links

• Just like images, links should always have a title if it is to be used as a placeholder or anchor tag. that is it has no content within the <a></a> tag.

• Tip for buttons: When using <div>...</div>, <span>...</span>, or <a>...</a> as buttons always add a role="button" attribute to the html tag. The role should be used for clickable elements that trigger a response when activated by the user. Adding role="button" will make an element appear as a button control to a screen reader. This role can be used in combination with the aria-pressed attribute to create toggle buttons.

The above example creates a simple button which is first in the focus order.

Audios & Videos

• Youtube videos:

• HTML videos:

• Other video types:

Code reviews don’t need to be – nor should they be – only about finding bugs and errors. They give us the opportunity to improve the quality of our codebase by providing feedback that helps move the code forward. Sure, that could be a fresh set of eyes catching a typo... but it’s also about learning new things, asking questions and talking through decisions, and giving praise when you see awesome code!

Our codebase is a team effort and it’s important to remember that we’re reviewing code, not each other. When you’ve spent hours/days working on a piece of code, sometimes it can be easy to take feedback personally. As reviewers, we can minimize the risk of misinterpretation (as well as provide better, more constructive feedback) by keeping a few points in mind:

• , and use the passive voice in your feedback

• When requesting a change, also , and perhaps even

• Remember that you can also use comments to ask questions or start conversations

For a deeper dive, we highly recommend reading How to Do Code Reviews Like a Human (, ). Many of us have found it quite valuable!

Preparing and Engaging

• All developers will be oriented to the digital development standards

• All developers will be briefed on shared resources (e.g. patterns library)

• Development approach will be approved by the CDO

• Approved approach will be scoped and and specified to the satisfaction of all parties with the minimum standards so the team can test that the code is what was requested

Managing project

• Product owner/Project Manager on Digital Team will oversee communication and management of project utilizing JIRA as as an organizing tool

• Regular communication (e.g. weekly meetings) or stand ups as necessary between partners to understand project timelines and dependencies

  • assigning tickets between teams

Accepting code in the codebase, deploying, and maintenance

• Digital team needs to peer review all code prior to deployment

  • JIRA tickets should have adequate solution and documentation for updating release notes

  • Developer standards should be adhered to for code development

• Digital team conducts the deployment into our deployment pipeline

• Partner is responsible for documenting and digital team is responsible for integrating the documentation into the Digital Team's Gitbook

• Developer to Developer hand over of code for future maintenance of the code

• Digital Team will update release notes when code is released into the PROD code base

Creating new pages

“Guide” or “Standards and best practices”?

If you’re documenting how to perform a task, organize it as a Guide. Most of the docs in our GitBook space will be Guides. (e.g. How do I start a new project?)

“Standards and best practices” is where to document things like What files need to be included in every project? What library should I be using?

Make sure you’re in editing mode

In order to add new pages, you need to switch into editing mode first. It’s easy to forget!

Use H1 and H2 headings to organize your content

GitBook will automatically create a list of hyperlinks from H1s and H2s as the page “contents” block in the upper-right of the page. Although it isn’t semantically correct, use H1s for all section titles within a page, and H2s for subheadings.

General tips and quirks

Moving in and out of editing mode

When you are in editing mode, any changes you make will be autosaved as one draft: you can click through and edit multiple pages without needing to save before leaving a page. When you’ve finished, make sure to save the draft! Note that the “cancel” button will discard all changes you’ve made, not just the page you are currently on. Your changes will not be live until you merge in your draft.

Adding a file to gitbooks

If you add a new file in github, then you must also add it to the summary for it to appear in gitbooks.

Contributor Covenant Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others' private information, such as a physical or electronic address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at digital@boston.gov. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4.

Local dev environment

Continuous integration

Code comments can save a lot of time and stress for the next person working in the codebase (spoiler: it’s probably future you) by reducing the effort to understand a piece of code, or the intent behind it. ; a well-placed explanatory comment can reduce or prevent the need, and allow a developer to continue on with their initial task uninterrupted.

Consider including a comment when...

Code is written a certain way for a particular reason

You ran into Something Weird during development

You’ve made a fix for a particular issue or PR

Solution has been copied from elsewhere

Version control

• All new software is checked in to GitHub.

• Legacy software that needs maintenance gets moved to GitHub.

• Absent a very compelling reason, repos are public from day one and source code is released under the public domain license.

Project structure

Local environment

Subdomains

Criteria

Boston.gov subdomains are assigned on a case-by-case basis. Typically, anything that is a core city service will qualify for a subdomain.

Naming Conventions

If the website qualifies for a subdomain, it should adhere to the following conventions:

Specific to the purpose

Descriptive of content on the site

Is not misleading/does not interfere with other City services

For an explanation on what DI is and why it's a good idea to use it, refer to the Drupal docs.

When you're using DI, you're asking the Service Container, which Drupal borrows from Symfony, to pass the correct object into your class so that you can interact with it in some way. See drupal docs for a full list of services provided by Drupal core.

The main thing to keep in mind is that any time you are writing a class in Drupal 8, you should be accessing external services through the service container (SC). If you use \Drupal::someMethod() within a class, that is a red flag as it's an opportunity to use DI instead.

Blocks, Controllers, Forms

Controllers (extending ControllerBase), blocks (extending BlockBase) and forms (extending FormBase) have special access to the SC. They can access it directly via their create()method. The example below gets access to the database and request_stack services, and then passes those into the __construct() method so that they can be used later on in the class. These services could also be accessed statically, \Drupal::database(), \Drupal::service('database'), \Drupal::request(), \Drupal::service('request_stack'), but since we're writing a class that's not the recommended approach.

  protected $db;
  protected $requestStack;

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container) {
    return new static(
      $container->get('database'),
      $container->get('request_stack')
    );
  }

  /**
   * {@inheritdoc}
   */
  public function __construct(Connection $db, RequestStack $requestStack) {
    $this->db = $db;
    $this->requestStack = $requestStack;
  }

In the other methods of our class, we can now access our services like this: $this->db->someMethod() or $this->requestStack->someMethod().

Roll your own service

If you're writing a class with functionality that will be (or could be) used multiple other places in the application, consider making it a service. For instance, if you're interacting with a 3rd party API, you may want to write a class to make common interactions easier (connect, fetch, etc).

In this case, refer to drupal docs for creating a service. The part of the .services.yml relevant to this article comes in the arguments line:

arguments: ['@database', '@request_stack']

This instructs Drupal to reach into the SC and pass the database and request_stack services into your class. This replaces the create() method in the example above. You can then add your services to your constructor like this:

  protected $db;
  protected $requestStack;

  /**
   * {@inheritdoc}
   */
  public function __construct(Connection $db, RequestStack $requestStack) {
    $this->db = $db;
    $this->requestStack = $requestStack;
  }

Now the other methods of your class can reference these services like this: $this->db->someMethod() or $this->requestStack->someMethod().

These accounts should all be members of the (secret) Digital Service Accounts GitHub team so we can keep track of them.

cob-deployer (Twicki) — This is a legacy service account that appears not to be currently used. It has 2-factor auth on but no registered SSH keys, so it doesn’t seem like any automated process can be using it. (The cloning of boston.settings as part of the Travis build comes from a “deploy key” specifically added to that repo.) As of 5/22 this account has no special permissions, and probably can be deleted if we can go a few weeks of deploys with nothing breaking.

cob-digital-atlantis (Atlantis) — Account for the Atlantis app used in Terraform deployment. Needs permission to the private digital-terraform repo so that it can see the Terraform templates and post its comments about plan and apply success and failure. (See: CityOfBoston/digital-terraform)

cob-digital-bot (Shippy-Toe) — Used by the internal-slack-bot tool as part of Digital monorepo deployments. Needs write access to digital repo so it can update production branches as part of deployment. (See: Digital Webapp DeploymenT)

cob-heroku (City of Boston Heroku Deployer) — Used for connecting GitHub and our dwindling number of Heroku apps. At this point just needs read/write access to patterns so it can make apps for each PR and report the deployment back. (Admin access is needed only when first connecting the account to Heroku so it can set up webhooks.)

State and Local Gitub Reps/Team/Sales Development Team @ GitHub (don't know much more)

Tanner Hogan, githogan@github.com

Eric Johnson, elstudio@github.com

Michaela Yamamoto michaelayamamoto@github.com

Since we are using Prettier to enforce basic code style, there’s no need to go into detail on those bits of syntax (e.g. always using semicolons, avoiding extraneous whitespace, etc).

General

• In nearly all cases, there should be only one React component per file. The file name should match the component name.

• A component’s story file (or test file) should be colocated with the component.

Naming

• File/component name should be descriptive.

• Use .tsx extension for React components.

• Storybook files should be named ComponentName.stories.tsx.

• Unit test files should be named ComponentName.test.ts.

• Interface and type names should be in PascalCase.

• Constant value names should be in ALL_CAPS.

Syntax

• Prefer <></> shorthand over <React.Fragment></React.Fragment>.

• Avoid var; use const by default, or let when necessary.

Comments

Use JSDoc style when documenting classes and functions, and standard // elsewhere in the code.

/**
 * Function used to count the number of eggs in a given nest.
 * 
 * Broken eggs will not be counted.
 */
function eggCounter(nest: Eggs[]): number {
  // If an egg is broken, we still need to return the count.
  return nest.reduce((count, egg) => egg.isBroken ? count : count + 1, 0);
}

TypeScript

Overriding type errors

Remember: TypeScript errors are for our benefit as developers, so we should always take the time to resolve type errors as often as possible. Override only as a last resort!

//@ts-ignore
this.setState({ [event.target.name]: event.target.value }); // avoid

this.setState({ [event.target.name]: event.target.value } as any); // preferred

React

Specifying defaultProps

Declare as a field on the component’s Class definition, and set its type as a Partial of the component’s Props interface.

interface Props {
  isReady: boolean;
  firstName?: string;
}

static defaultProps: Partial<Props> = {
  isReady: false,
};

Using Refs

See https://reactjs.org/docs/refs-and-the-dom.html for detailed information. When referencing a Ref in your code, don’t forget that you need to use the current attribute to access the actual DOM element!

export default class CustomInput extends React.Component {
  private inputRef = React.createRef<HTMLInputElement>();
  
  private logValue = (): void => {
    console.log(this.inputRef.current.value);
  }

  render() {
    return (
      <input type="text" ref={this.inputRef} />
    );
  }
}

Emotion

See the Emotion guide.

The DoIT Digital team is currently working on a number of projects to improve the digital experience for both City of Boston’s constituents and workers. We also have a backlog of projects that are slated to begin over the next number of months.

As the project/product management team on the Digital Team grows, it will help immensely to implement some common baseline project management practices across projects so we can track digital projects from kick off to implementation.

This means we will use the same tools, processes, and language across all projects so anyone on the digital team will understand where we are on any given project and what team members are working on at any given time. This will help us accurately report on project timelines internally and out to stakeholders.

We are not going to introduce any new project management tools. We want to leverage the tools we currently use to help establish these procedures. We will continue to use Google suite and GitHub. As we establish some best practices across the Digital Team, there will always be room for improvement and modifications as we try to figure out what works best.

We have been exploring how to use GitHub to help us track projects. GitHub recently introduced a beta version of Projects we can leverage to give us a dashboard for ongoing project work.

We created a Digital Project Board on GitHub and anyone can link issues from other projects to this main project to track what is in progress. We are continually trying improve how we view projects on this board. Below we will outline and define how Digital team members should use the best practices we are putting in place.

Projects

By definition projects are a sequence of tasks that must be completed to attain a certain outcome. Digital team projects can vary in size and scope based on the requirements. A project team should be made up of the following:

• Product Owner/Manager

• Project Manager

• Stakeholder(s)

• Developer(s)

• UI designer(s)

We use GitHub to keep track of the Digital team’s development work. You can find the repositories at https://github.com/CityOfBoston. New projects should be set up under Projects>Projects(Beta). Issues in these projects can be linked to the new Digital Project Board so we can view what work is in progress at a glance.

Setting up and tracking a project

New projects can be set up under Projects>Projects (Beta). Issues in these projects can be linked to a new Digital Project Board. Linking high-level issues associated with a project allows us to see what work is in progress at a glance.

You can find the steps to set up a new project and how to link issues to the digital project board here: Project Set Up in GitHub

Project Managers should set up a GitHub Project for each of their projects. Project Managers can set up and run their project in a way that works for their team. However, using some of the same conventions outlined in the slides above will help establish common practices.

Project Managers will be assigned to approved projects from the backlog when they are ready to kickoff. They will be responsible for managing projects from start to finish.

The Product Owner/Manager defines the vision for the product and works closely with the project manager on project timelines. Product Owners are responsible for triaging bugs, new project requests and prioritizing the product backlog.

Project Managers are responsible for the following:

• Scheduling Kickoff meeting - invite stakeholders, Devs, UI Team

• Project Set up in GitHub

• Gathering requirements

• Documentation

• Scheduling regular project team meetings (scrums, check ins etc.)

• Communication between stakeholders and project team

• Tracking the project in GitHub (creating tasks, issues)

• Writing acceptance criteria

• Linking appropriate project issue tickets to Digital Project Board for tracking

We have a shared Digital Google Drive where you can find the Digital Team Projects folder. This folder contains a specific project folder as well as a Templates folder. The templates folder contains a Project Overview Document template that Project Managers can use to document key project information. Anyone on the Digital team can add tools they find helpful into this folder for anyone to utilize.

We also have a GitHub project called Digital Completed Projects - (Maintenance)

This project is reserved for issues that arise on projects that have been completed. These may be bug fixes or small enhancements to projects that do not meet the requirements of a project.

Project Tracking Common Practices

You can find the steps for setting up a new project in Git Hub here: Project Set Up in GitHub. As stated above each PM can set up and run their projects in a way that works for their team. Below are some suggested common practices you can follow.

Once a project is set up in GitHub, it will be easy to track issues using the following status’/swim lanes:

• To Do/Backlog

• Triaged/Sized

• In Development/In Progress

• Ready for Review/QAT

• Ready for Production

• Done

Issues/Tickets

• Created by the PM and or Lead Developer and added to a project

• Issues contain tasks or acceptance criteria for the development team

• Prioritized by the team in the backlog based on sizing and timing

• Moved through the swim lanes or status’ by any team member as the work is being completed

• Once tested and considered complete closed by PM or Lead Dev

QAT(quality assurance testing)

• Once an issue is assigned QAT status the PM should review the work in a test environment against the acceptance criteria in the ticket

• If the project involves extensive User Facing components the UI team member(s) should also review the stories and sign off as complete

• PMs or UI team members should add any comments or questions directly into the ticket for the developer to address

• Some larger projects may need to involve outside vendors for comprehensive testing

• PMs should work with Dev to team to create test scenarios and use cases for testing

Project closure

• All issues/tickets have been tested and deemed done

• Code is successfully deployed to Prod

Project Development

We do have a number of positions we are trying to fill at DoiT- Digital to oversee and work on project development work. When we are staffed properly the development teams will be split into two areas:

1. New work team - this team will work on larger development projects that require new development and feature work. This team will work with project managers who are overseeing those larger projects.

2. Maintenance team- this team will work on maintenance and smaller bug fixes/issues that are not deemed to have escalated into projects. This team can undertake smaller projects if they have capacity. Maintenance teams will not typically need project management oversight, they will be managed by the lead developer.

Digital Project Board

We set up a Digital Team Project Board in GitHub to capture active project work across the Digital Team. We have a list of projects in the backlog swim lane. New projects will be vetted and approved by leaders on the Digital Team, based on available resources and budget. When a project is ready to begin, it will be assigned a Project Manager, Dev, and UI Team. The project will be added to the Digital Project Board. The Project Manager will be responsible for its progress.

Project managers can link appropriate project issues to this board and will be responsible for moving it to the applicable swim lane based on the project status.

Draft Tasks

Once you have a project setup, you can create Draft Tasks. These are not assignable or attached to a repository. Draft Tasks can be given a status. Project Managers or others can use these tasks at their discretion.

For example, tasks can be created to capture initial development work and acceptance criteria before being converted to issues.

Issues

Draft Tasks can be converted to Issues. Issues need to be associated with a repository. Issues can be assigned to multiple projects and people. Issues can be moved between swimlanes or given a status. Project managers can use issues to track the work on their project done by anyone on the team.

All issues should be assigned a project. If there is not project associated with a specific issue it can be assigned to the following project in GitHub: Boston.gov - Non Project Issues

Project managers should create a high level issue(s) to represent project work, which may have its own project board, and link it to the digital project board so the team can track ongoing projects.

Repositories

Repositories are where our code base lives for each project. Issues need to be linked to a repository. We are in the process of cleaning up and organizing the repositories. The Digital Team works in a handful of repositories:

• Boston.gov - d8

• Digital

• Patterns

• Digital Documentation

• Cityofboston.gov - this is specific to any migration projects from the old City of Boston site to Boston.gov

If you have a question to where an issue might be assigned please ask the lead developer on your project. We may configure these differently in the future based on how projects will be managed moving forward.

Meetings

Project meetings are up to the Project Manager’s discretion. A project kickoff meeting is recommended so everyone on the team understands the Project and the roles of all team members.

Regularly scheduled project meetings are a helpful way of keeping the lines of communication open as well as tracking and moving the project forward

Suggested Meetings:

Dev Projects:

• Project (scrum) meetings with devs on an as needed basis for a project - attendees to be determined by the team

• Project retrospectives on an as needed basis for a project with PM's, Product Manager and devs (CDO optional)

Digital Team:

• Weekly group (content, social media, design, dev) meeting on Mondays to report progress last week and agree the groups priorities for the week

• Weekly formal digital meeting where Information from CDO is passed to the team, questions are asked to the CDO etc. Held on the day after the DoIT Direct Reports meeting

• Weekly demo meeting where work can be showcased, brags and learns shared with the group. SME's from other teams can be invited as relevant to present (e.g. Daniel showing ArcGIS capabilities) digital-relevant information

• Monthly one-on ones between Individual and CDO with individuals team leader present.

Communication

The Project Manager should be the main point of communication for a project. The team can decide on how they want to communicate with each other and stakeholders throughout the project. Setting up a project team space in google chat might be helpful for quick check-ins and questions during the project.

Project communication should be established at the kickoff meeting.

Backlog

A backlog is a prioritized list of work for a project that is derived from the project requirements. This can include tasks and issues for anyone on the team. The Project Manager should manage the backlog for projects with input from the team. Keeping your backlog up to date will help report out any blockers and project timelines.

Labels

Each repository has its own set of labels. The Digital Team will be meeting to create a list of 10-15 labels we can use across repositories. We can use labels to filter work on the Digital Project Board.

We are using this google doc to pair down the list: Labels

If you need to add a label to a repository the team should approve so we can make sure we add it to all repositories.

Milestones

Milestones are associated with repositories. Currently we are using Milestones in each repository to identify Low, Medium and High priority for issues not related to projects. We can group these issues into these categories for easy viewing on project board list views.

New Project Work

We have created a project intake form that people can fill out if they are interested working with the Digital Team on a project. This form can be shared with anyone who wishes to work with the digital team on a project: Digital Team Project Request Form

If you want to add this to your email signature here is some suggested phrasing:

Have an idea for a digital project or application? Submit your ideas here!

Enhancement Requests/Bug Reporting

If someone on the Digital Team receives a request from another Department at City of Boston to report a bug or discuss an enhancement for a previously completed project on Boston.gov we established the following procedure to triage and prioritize these issues:

1. A GitHub issue/ticket is created in one of the following projects and assigned to James Duffy

   • Digital Completed Projects (Maintenance)

   • Boston.gov - Non-Project Issues

2. The Boston.gov Product Owner - James Duffy - will triage the ticket

3. The Product Owner will connect with the original reporter of the issue and gather any requirements

4. The Product Owner will discuss the issue with the Development Manager -David Upton- they will decide if the issue is a bug or a potential new project

5. The Product Owner will prioritize the work

6. Bugs: The Dev Manager and Product Owner will allocate to the appropriate developer

7. Projects: Product Owner will hand it off to a Project Manager to start the new project process detailed in this document

Continuous deployment apps

• We push changes to production as soon as they’re ready. This keeps us from piling up inventory. Shipping small batch sizes is also safer.

• We’ve built a deployment system that has zero-downtime, so it’s always safe to push.

• See each repo’s documentation for instructions on how to deploy it.

Fixed-schedule deployments

• Changes are made against a develop branch rather than production

• develop branch is pushed to a staging environment on a weekly schedule

• Issues in “Inventory” Kanban column get moved to “Staging” column

• Issue creator / feature owner validates fixes on staging

• Code gets merged to production branch and pushed to production the following week

• Issues move from “Staging” column to “Closed” after pushing to Production

Possible change: Adding a “Staging” lane to differentiate with “Inventory” (not yet pushed to staging).

General

• Changes are made on feature branches and merged via Pull Request, regardless of whether those PRs are reviewed.

• Preferred naming convention for a feature branch is service-name/feature.

• Never commit directly to develop or production branches.

• Rebase to a single commit before making a PR.

• Commit messages should be written in present tense.

Pull Requests

• PRs should be merged by the assignee, who is typically the person who made the PR.

• Assignee should delete the branch once it has been merged into develop.

• Code reviews are required if more than one engineer has interest in the repo, regardless of the relative experience between the engineers.

• Code reviews take priority over feature work, and must be responded to quickly.

• Reviewer is responsible for approving changes detected by Percy.

Git Branches

For Drupal see:

Git Strategy

Git has a reputation for being complicated, and part of that is because the problem that it addresses — distributed version control — is a complicated problem.

Here’s a (hopefully) short way of thinking about Git that might help you avoid getting your repo in a messy state, or at least guide you out of it when it happens.

Commits

To be successful with Git, it’s important to understand its model: starting from nothing, a series of patches, called “commits,” that, over time, build up a repository.

Commits each have an identifier, known as a “SHA” because they’re generated by taking a SHA hash of the commit’s data. Canonically they’re a 40-character hex number, but are usually referred to by the first 8 characters because those are probably unique in the repo.

Sometimes these commits follow one after another. Each has a single parent and modifies the repo in some way, like steps in a LEGO instruction book.

Other times, commits “merge” the changes from two different “parent” commits together back into one, like two roommates coming back together after the holidays. If the commits changed different parts of the repository — say, everyone got new clothes for their own closets — this merge happens easily and automatically. But, if they both brought posters that they wanted to hang in the same place in the common room, that’s a conflict that needs to be resolved.

Part of good shared Git repository use is communicating with your teammates and merging small changes frequently. The longer you spend collecting bric-a-brac on your own, the more likely it is your roommate has moved the shelf you were planning on using when you got back. And, if you have a large change planned, like refactoring a lot of code, it’s best to tell your co-workers not to pick out curtains until after the metaphoric common room has been repainted.

In concrete terms:

• Regularly update your local repo with the latest version of the code by using git fetch or git pull and merge / rebase those changes into your in-development branch.

• Keep your changes focused when you can, adding single features or modifying just a few files at a time.

• When a necessary change is large, let your pals know what parts of the code base you have designs on so they can avoid making their own changes in those areas until you’re done.

This will minimize the number of conflicting changes, which will reduce the number of times your Git repo gets in a rough state.

Branches

A lot of attention when using Git is focused just on branches, but it’s helpful to think of them in terms of commits, since that’s how Git does.

A branch is nothing more / less than a name that is referring to a particular commit. What makes them particularly useful (and distinct from Git tags) is that they can be changed to point to a different commit.

It’s worth underlining that the history of changes that lead from nothing to a code base is kept not in the branches, but in the commits. The develop branch just points to a particular commit and it is that commit — not the develop branch — that is a diff against one or more parent commits, all the way back to 0.

In order to be convenient and useful, the git tool will update branches — pointing them at different commits — automatically. But a key to understanding Git is to distinguish between what role the commit has vs. the role the branch has.

For example, git commit is used to make a new commit. It takes all the staged changes in your working directory and a commit message, and makes a new commit with your directory’s current HEAD commit as its parent. It then considers the new commit the current HEAD of the directory.

This works even when you’re not using branches, what Git refers to as “detached HEAD state.” You can still create commits. You’ll need to use their SHAs to reference them, but they’re still there.

Now, if your repo is currently checked out to a branch (because you did git checkout my-branch), the above description of git commit all still applies. The git tool just does the added behavior of updating the name my-branch to point to the new HEAD commit you just made.

Once you think in these terms, Git commands like reset make a little more sense. reset takes the current branch and points it at a different commit.

So, to undo a git commit, you can run git reset HEAD^ (HEAD is a special name for “what’s checked out now” and ^ means “the commit before”). reset by default does not change the files on disk, so you didn’t lose any work. But, since you’ve changed what my-branch is pointing at, the changes that were previously committed now appear as uncommitted. (If you check your terminal history and find the SHA from the commit, you could run git reset <SHA> to re-do the commit by pointing the branch back to it.)

An important caveat: commits that are not either pointed to directly by a branch or in the branch commit’s ancestry are eligible to be garbage-collected by Git. They tend to last in your local repository for about 30 days, and can be referred to by their SHA during that time.

Useful Tips

Shell Prompt

Make sure your shell prompt is Git-aware. It should show you what branch you’re on and ideally if there are uncommitted changes in your directory.

Editor

Use an editor that is Git-aware, in particular one that shows you diffs (preferably side-by-side) and lets you edit in the diff. This is invaluable for seeing your work and doing pre-push editing passes on the code before putting it up as a PR.

Visual Studio Code is very good at this, with the caveat that if you diff staged changes against the latest commit you can’t edit them with the diff tool. You can edit unstaged changes, however. You can git reset HEAD to unstage everything if you need to, or git reset HEAD^ to un-commit your previous commit (while preserving its changes in your working directory).

Aliases

You can add “aliases” to your ~/.gitconfig file that mean you don’t have to type as much on the command line.

[alias]
	co = checkout
	st = status
	amend = commit --amend --no-edit
    delete-merged = "!git branch --merged | grep  -v '\\*\\|master\\|develop' | xargs -n 1 git branch -d"

These make git co short for git checkout and git st short for git status.

git amend is useful for adding the currently staged changes to the previous commit. This is very useful in development to pre-squash your commit and avoid a chain of “tmp” commits in your history. (Use git commit --amend if you want to add to the previous commit but edit the commit message.)

git delete-merged is a cute little housecleaning command that removes all local branches that point at commits that are parents of the current branch. So if you do: git fetch git co origin/develop git delete-merged it will remove any local branch that you’ve already merged into develop, keeping the output of git branch cleaner.

Recipes

Starting a new change

If you’re working on a new feature or bug fix, you’ll want to make a particular branch for it so it can be code-reviewed as a PR. (See our GitHub working agreement for proper behavior.) Since you’re intending to merge it back into the develop branch, it’s best to start by branching off of develop. But, not just anywhere, but the latest version of develop that your coworkers / roommates have committed.

$ git fetch
$ git checkout origin/develop
$ git checkout -b my-new-branch-name

This first uses fetch to update our local cache of the default origin remote (i.e. the GitHub repository) to the absolute latest. It then checks out the commit that origin’s develop branch is pointing to in “detached HEAD” state. Finally it creates a new branch with your new name. (You can use git co if you’ve put in the aliases from above.)

Following this recipe will ensure that you’re starting new work from the absolute latest that has been checked in to GitHub and will keep you from accidentally committing things to a local develop branch and getting mixed up.

Context-switching

Sometimes you’re working on one thing in your working directory but then realize that you need to put it aside and make a quick bug fix or something.

While Git provides a “stash” feature for saving things, it can be easy to lose or forget about the contents of your stash. Better to make a new commit.

Saving your work

$ git add -A
$ git commit -m tmp

This adds all changes, including new files and deleted files, to the index and then commits them all with a “tmp” commit message.

Then, follow the above “starting a new change” recipe to get yourself set up for the fix you need to make.

Restarting your work

$ git checkout my-previous-branch
$ git reset HEAD^

Use this recipe to get back to what you were working on, with a git reset HEAD^ to get rid of the “tmp” commit while still preserving the changes from it in your working directory.

Updating your branch with the latest

It’s a good habit to make sure your branch is based on the latest changes from the branch you’ll be merging into (probably develop). You also sometimes need to do this if your change is going to rely on something that got merged after you started working on it (often because of the above context switch).

Fingers-crossed method

$ git fetch
$ git rebase origin/develop

This method updates our cache of origin as before, and then runs git rebase. Rebasing is a powerful capability of Git that can also get you into a mess of trouble. The first thing rebase does is the equivalent of a reset --hard to make both your current branch and the contents of your working directory match origin/develop. It then re-commits every change from where your branch and origin/develop diverged. (The equivalent of repeated git cherry-pick.)

If your changes are in conflict with ones from the latest version of develop, you’ll have to follow the instructions to resolve those.

In general, rebase is preferred because it leaves your Git history nice and linear and clean. It’s as if someone time-travelled back to when you were first working on the feature and gave you a different place to start from.

But, there are caveats that can blow up in your face, which is why we call it the “fingers-crossed” method. git is going to apply your commits individually, and in order. If any of them have conflicts with the new updates, resolving them can be tricky. For example, say you have commits “tmp”, “tmp 2”, and “fixed” that all change the same code. Say it took you a few tries to get a bit of code right. Remember that commits are diffs against their parent, so “tmp 2” knows how to apply changes against “tmp”, and likewise “fixed” expects the part of the repo that it affects to look like “tmp 2”.

If you rebase and there’s a conflict when applying “tmp” you’ll need to resolve it before git rebase can proceed. It can be tempting, since you’re now editing the code, to make things look like how they ended up with “fixed”, but that’s not what you need to do. You need to resolve things so that “tmp 2” can be applied correctly.

This is one reason why you should squash your changes as you develop. Rather than make “tmp 2” and then “fixed”, use git commit --amend to re-do the “tmp” commit. There’s no value in preserving those intermediate broken states forever in your repo’s history, after all. Rebasing just one commit is always going to go a lot more smoothly than multiple commits, since you don’t have to worry about correcting things to those intermediate states.

If you end up in a bad, confusing place, just type git rebase --abort to cancel the rebase operation and try again with the “merge/reset” method below.

Merge/reset method

If git rebase gave you trouble and you also don’t mind squashing your commits and re-writing the commit message, you can use this method.

$ git fetch
$ git merge origin/develop
$ git reset origin/develop
$ git add -A
$ git commit

This starts with the easy-to-forget git fetch to get us up-to-date. It then merges the latest from the develop branch into our current branch. Unlike rebase, merge does not rewrite history and re-apply your commits. This means that when you resolve conflicts you only need to do it between the latest versions of the develop branch and your own. You don’t have to do the intermediate state stuff that made rebase painful.

When used in this way, however, git merge will typically leave behind a “merge commit” that points to the two parents (whatever commits origin/develop and your branch were on when it was run) and contains any diff necessary to resolve conflicts. This is an untidy artifact.

To excise the merge commit from our branch’s history so that it’s neat, we do a git reset origin/develop to point our branch to develop’s latest commit. Since reset without --hard doesn’t change the working directory at all, all of our changes, including the conflict resolutions from the git merge , are all still there. git add -A followed by git commit bundles them all up and commits them.

Extracting changes for review

This is a combination of “Context switching” and “Updating to the latest.” The scenario is that you’re knee-deep in work on a branch when you realize that part of what you’re doing is distinct enough that it belongs in its own PR. Two small PRs is kinder and safer than one big PR.

You should start this by following “updating to the latest” so that your branch is up-to-date with develop.

$ git reset origin/develop
$ git add …
$ git commit
$ git add -A
$ git commit -m tmp
$ git co <sha>
$ git co -b <my-new-branch>
$ git push

Ready?

This starts with a git reset so that all of the changes we’ve been working on are out-in-the-open as uncommitted. (This is why making sure we’re up-to-date with origin/develop is so important before starting.)

Then, use git add <filename> to selectively add changes in that you want to put up for review now. If some files have changes where you only want some of the changes you can often use your editor or git add -p to stage just what you need.

Once that’s done, do a git commit and use a proper commit message to describe these changes. Keep note of the SHA of this new commit. You’ll need it.

Next we add everything else and commit it, which you might recognize from the context-switching recipe. It's relevant as well that this commit has your intermediate commit as its parent. That means that your future changes will probably merge cleanly after the intermediate commit is merged.

git co <sha> with the SHA of the intermediate commit will check it out as a detached HEAD. This removes any of the later changes from the working directory, where they could mess up pre-push tests and such. Then it‘s a git co -b to give these changes a name and git push to send them up.

Dealing with intermediate changes changing

Sometimes, either because pre-push tests fail or because you got PR feedback to make changes, the version of your extracted change that got committed is different from the one your later work is based on.

This can be especially tricky if you were tidy and squashed your changes, since the repo now has two slightly different commits that make essentially the same changes. And “slightly” is more than enough to give them different SHAs, which makes them completely different to Git.

You might have some luck with the “merge/reset” method of updating after the extracted changes get merged to origin/develop, but you can often rebase you way out of it as well.

$ git fetch
$ git log
$ git rebase HEAD^ --onto origin/develop

After the standard git fetch, use git log to see how many commits you’ve made since extracting the other PR. If you haven’t done anything since, or have been using --amend to squash changes, there will only be one. If there are more, you’ll need a ^ after HEAD for each change.

This use of rebase takes all changes since HEAD^ (meaning: the commit before the current one) and replays them on to origin/develop. Depending on whether or not the test/PR fixes you made intersect with your later work, this will be either annoying to resolve or automatic.

Being defensive

Preparing for disaster

Anything you’ve committed locally is saved in your local repository for 30 days, even if no branches are referring to it.

Before you do anything risky to your repo, it can be good to just run a git add -A / git commit -m tmp to get it stored. You can then note down the SHA of that commit or even run git branch saved-branch-name to checkpoint it with a more permanent name, before running git reset HEAD^ to undo the commit.

Recovering from disaster

If you’ve been committing fairly regularly, you can typically always get yourself back to a good state. If you lost a SHA or need to otherwise undo, you can run git reflog to print out a history of all of the commit/checkout–type changes you’ve made in your repository. That can often help you find a place you want to get back to.

git reset --hard <sha> is a useful tool to get your branch and working directory to a specific commit, particularly after a merge or rebase goes south, and you can try again.

Matters of Opinion

• “Squash” your branches down to a single commit before pushing them up for review. The local checkpoints you made along the way to finishing your feature are not relevant for the future.

• It’s ok to force-push. Doing a git push --force has historically been super-dangerous because Git would update all branches on the remote repo to what they look like locally, destroying other folks’ work. This has given it a bad reputation. But, force pushing can be useful for keeping the commit history clean, such as when implementing changes from a PR. The rule of thumb is: don’t force-push branches that other people are using. That gets messy because you’re rewriting history on someone and they have to take special actions to accommodate you. But typically you shouldn’t be working from other people’s branches. Get them committed to develop!

• Give your main branch a better name than “master.” It’s a word that has not-great connotations while also being wholly undescriptive. Is your main branch where development work happens? Call it “develop”. Does it automatically reflect production? Call it “production”.

• Don’t use a your local branch called develop. In fact, run git branch -D develop to delete it. It’s too easy to start working from develop without realizing that it’s long out-of-date relative to GitHub, or to make commits on your local develop branch that you then can’t find anymore. Use git fetch and git checkout origin/develop to get your working directory to the latest from GitHub.

Main City Website (boston.gov)

The main City of Boston website is a CMS developed using Drupal (a PHP - MySQL framework) hosted on Linux - Apache (LAMP) in the Cloud. Implemented as Drupal 7 in 2016, migrated to Drupal 8 in 2019, then Drupal 9 in March 2022.

Cityofboston.gov

Legacy website and applications (pre-Drupal) hosted 'on-prem' at the City. Nearly all of these items live on zpcobweb01 with sql databases -- mainly ZPDMZSQL01 and ZPCOBSQL22. Most of these are .asp or .aspx files.

Web Applications

Our web app stack includes React, NextJS, Node.js/Hapi, and you can check out a more complete list by following the link below.

Some of these are attached to vsql22 for data.

Third-party integrations and tools

Libraries

@cityofboston internal modules

Useful modules we’ve created and use across our apps in the monorepo.

Hosting

Apple Developer and Google Play

Digital is in charge of maintain/help support/be technical advisors on nearly all of the mobile apps obtained by the City. They can be found on these.

Amazon Web Services

• We use for describing our infrastructure. See the repo.

• Do not make one-off changes in the UI or with the command line. Everything should be updated through Terraform so we have transparency about what we’re running and why.

• Terraform changes should be made through .

Acquia Cloud

• Acquia externally hosts our main website, boston.gov in their cloud instance.

Heroku

• Heroku is appropriate for very one-off apps (such as the 311 crowdsource app) where we don’t mind not being on a boston.gov URL or waiting for the dyno to spin up after inactivity.

• We only want to use free tier dynos going forward.

• We need to get off all paid Heroku services, migrating to AWS/S3 as appropriate. Staging apps, however, should generally deploy to AWS to match production-like environments.

Monitoring

We should never be surprised by an outage. CloudWatch and/or Updown.io should be monitoring our apps and the services they depend on.

If an alarm goes off regularly, either its root cause should be fixed or the alarm should be adjusted or removed.

CloudWatch

• We have a handful of CloudWatch alarms to monitor our instances, VPN, and services.

Rollbar

• Exceptions we cannot eliminate should be silenced on the Rollbar side or prevented from throwing in the first place. If necessary, they should be converted to logs that can be monitored.

Updown.io

• Yes, parking tickets goes down every night and it’s annoying.

General documentation

This (GitBook) is the place to document technical information that isn’t specific to a particular project. We should be liberal with documenting our workflows and standards, and aim for the standard that any new developer could independently find everything they needed to start working on any of our technical tasks.

Project-specific documentation

Any technical information that’s specific to a particular project should be in a README.md at the root directory of the project’s source files. Examples include: how a new developer could install the project locally, a list of npm/Yarn tasks... basically, anything that “should be in a README”. is a great reference for the types of information that should be included.

Also see project specific information further down in Gitbook. The project’s page in the “Project” section of this GitBook should include a link to its README on GitHub.

Code comments

Documentation comments are super-useful! See the dedicated page for more guidance.

On demand instances of the Drupal site (boston.gov) are useful to demonstrate new features or functionality sand-boxed away from the

These on demand versions of boston.gov are designed to be housed on a near-duplicate environment to the production site, and be in a normal browser from anywhere by people with the correct link.

Set-up a site branch (or tag) on Acquia.

Elsewhere this might be termed spinning up an on-demand instance of the site.

1. Make sure you have the latest copy of the main Drupal 8 repository cloned to a folder <repo-root-path>.Checkout the branch develop and make sure the latest commits are pulled (fetch+merged) locally.

2. Commit your work to a new branch (on-demand-branchname) off the develop branch .

3. Push that branch to GitHub, but do not create a PR or merge into develop.

4. Edit <rep-root-path>/.travis.yml file and make the following additions: (Note: replace <on-demand-branchname> with on-demand-branchname.)
5. Edit <rep-root-path>/scripts/.config.yml file and make the following additions: (Note: This partial example addition is configured to deploy to the Ci environment on Acquia) (Note: replace <on-demand-branchname> with on-demand-branchname.)
6. Commit the .config.yml and .travis.ymlchanges to on-demand-branchname and push to GitHub - but do not merge into develop.

7. Make a small inconsequential change to the code and commit to the on-demand-branchname branch, and push to GitHub. This will cause the first-time build on Travis, and deploy into the on-demand-branchname-deploy branch in the Acquia Repository.
9. The "on-demand" environment is now set. Users may view and interact with the environment as required. See Notes in "gotcha's" box below.

10. Once you have finished the demo/test/showcase cycle, you can merge the on-demand-branchname branch to develop - provided you wish the code changes to be pushed through the continuous-deploy process to production.

11. Finally you can detach the on-demand-branchname branch from the Acquia environment, and set it back to the tags/welcome tag.

Public URL's for the on-demand environments.

You can direct users to the URL's below, select the environment you switched to the on-demand-branchname-deploy branch (in step 8) from the table below.

On-demand instance gotcha's:

Local Build

Local Development

Deploy to Develop (includes automated testing)

Deploy to Staging (includes automated testing)

QA

Deploy to Production

Acquia Hooks

• In the CoB Drupal 8 private gitHub repository edit the Acquia Hook scripts in the /hooks/common folders, looking for the following code in thepost-code-update.sh and post-code-deploy.shfiles:

  Copy

  if [[ "${target_env}" == 'uat' ]] || [[ "${target_env}" == 'ci' ]] ... ; then

  and adding in a new condition for the new envname:

  Copy

  ... || [[ "${target_env}" == 'envname' ]] ...

  save the updated files and commit to the private repo.

• In the CoB Drupal 8 private gitHub repository find the following line in the script at/hooks/common/cob_utilities.sh file (approx line 270):

  Copy

  elif [[ "${target_env}" == "ci" ]] || [[ "${target_env}" == "uat" ]] || ... ; then
      site_machine_name="none"
  fi

  add in the a new condition for the new envname:

  Copy

  ... || [[ "${target_env}" == "envname" ]] ...

  save the updated file and commit to the private repo.

Acquia Settings

• In the CoB Drupal 8 private gitHub repository find the following line in the script at/sites/default/settings/hooks/common/cob_utilities.sh file (approx line 63):

  Copy

  ...
  elseif ($_ENV['AH_SITE_ENVIRONMENT'] == 'uat') {
    $conf['acquia_purge_domains'] = array(
      'bostond8uat.prod.acquia-sites.com',
    );
  }
  ...

  add in a new else statement for the new environment:

  Copy

  elseif ($_ENV['AH_SITE_ENVIRONMENT'] == 'envname') {
    $conf['acquia_purge_domains'] = array(
      'bostond8envname.prod.acquia-sites.com',
      'd8-envname.boston.gov',
    );
  }

  (replace "envname" with the new environment name)

• In the same file find the following section (around line 79):

  Copy

  ...
  if (in_array($siteEnv, ["test", "ci", "uat"])) {
    $settings['file_public_path'] = 'sites/default/files/linked';
  ...

  and add the new environment name to the list of environments.

  Copy

  if (in_array($siteEnv, ["test", "ci", "uat", "envname"])) {

  save the updated file and commit to the private gitHub repository.

Drush

• In the CoB Drupal 8 private gitHub repository edit the drush environment definition script in the /drush/sites/bostond8.site.yml file. Add a new entry at the bottom of the file:

  Copy

  envname:
    root: /var/www/html/bostond8.envname/docroot
    ac-site: bostond8
    ac-env: envname
    ac-realm: prod
    uri: d8-envname.boston.gov
    host: bostond8envname.ssh.prod.acquia-sites.com
    user: bostond8.envname
    envname.livedev:
      parent: "@bostond8.envname"
      root: "/mnt/gfs/bostond8.envname/livedev/docroot"
    paths:
      drush-script: drush9

  (replace envname with the new environment name). Save the updated file and commit to the private gitHub repository.

.htaccess

• In the .htaccess file in the CoB Drupal 8 private gitHub repository alter the domain filters as follows: Everywhere you see this pattern in the file:

  Copy

  RewriteCond %{HTTP_HOST}... dev|stg|ci|ra|uat ...

  Add the following entry:

  Copy

  RewriteCond %{HTTP_HOST}... dev|stg|ci|ra|uat|envname ...

  Save the updated file and commit to the private gitHub repository.

Acquia Cloud

• Login to the Acquia Cloud Console and click on the bostond8 application.

• Click on the new environment to open the configuration page for that environment.

• CRON: Click on "Scheduled Jobs" and create the following new Job: Job name: Envname Site Cron Command: cd /var/www/html/${AH_SITE_NAME}/docroot && drush @bostond8.envname cron -dv &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log Command frequency: */15 * * * * (entered as a string)

• ENVAR: Click on "Variables" and create variables copied from the dev environment.

• DOMAIN: [optional] Click on Domains and add an edit sub-domain. (this is requested from the LAN team, and should be in the pattern of d8-envname.boston.gov. Ask them to set it up the same way that d8-dev.boston.gov is set up. The DNS they create would ideally be private (only to city hall) but they may need to make it on the public DNS servers, which is OK too).

Single Sign On

The following steps need to be completed to allow single sign on via Ping Federated.

• aa

Using the Environment

To use the environment as a Drupal site, you need to attach a branch from the Acquia git repository. For detailed instructions see On Demand section.

City of Boston use docker containers for local development.

Lando is used by the Drupal development team to manage the docker containers and provide basic tooling for the local development environment.