From aec74ea6adad2a56ce6c12ae7173c6a026f0c9eb Mon Sep 17 00:00:00 2001 From: Owen Barton Date: Wed, 11 Dec 2024 16:31:15 -0800 Subject: [PATCH] Apply prettier list indents. --- about-civicactions/culture.md | 42 +-- .../diversity-equity-inclusion/README.md | 8 +- .../affinity-channels.md | 44 +-- .../defining-dei.md | 40 +-- .../deia-get-involved.md | 4 +- about-this-guidebook/editing-the-guidebook.md | 84 +++--- about-this-guidebook/guidebook-governance.md | 4 +- .../markdown-for-guidebook.md | 26 +- about-this-guidebook/why-guidebook-is-open.md | 6 +- about-this-guidebook/writing-style-guide.md | 8 +- common-practices-tools/agile/README.md | 12 +- .../agile/backlog-refinement.md | 2 +- .../agile/daily-scrum-calls.md | 12 +- common-practices-tools/agile/sprint-cycle.md | 28 +- common-practices-tools/agile/sprint-demo.md | 2 +- .../agile/sprint-planning-meetings.md | 4 +- .../agile/sprint-retrospectives.md | 8 +- common-practices-tools/agile/tickets-cards.md | 60 ++-- common-practices-tools/balance-scores.md | 10 +- ...practices-for-managers-and-team-members.md | 34 +-- .../contribution/contrib-first.md | 48 ++-- .../difficult-conversation.md | 56 ++-- common-practices-tools/security/README.md | 122 ++++----- .../security/contingency-plan.md | 118 ++++---- common-practices-tools/security/encryption.md | 18 +- common-practices-tools/security/gnupg.md | 10 +- .../security/incident-response-checklist.md | 54 ++-- .../security/incident-response-plan.md | 256 +++++++++--------- common-practices-tools/security/incidents.md | 34 +-- .../security/securing-your-workspace.md | 10 +- common-practices-tools/security/yubikey.md | 68 ++--- common-practices-tools/skills-base.md | 98 +++---- .../software-and-support/README.md | 20 +- .../software-and-support/email.md | 18 +- .../software-and-support/github.md | 4 +- .../software-and-support/google-calendar.md | 28 +- .../software-and-support/google-docs.md | 14 +- .../software-and-support/google-meet.md | 42 +-- .../software-and-support/jira.md | 34 +-- .../software-and-support/markdown.md | 10 +- .../software-and-support/mural.md | 10 +- .../software-and-support/sauce-labs.md | 22 +- .../software-and-support/slack.md | 38 +-- .../software-and-support/zoom.md | 26 +- common-practices-tools/telephone.md | 8 +- company-policies/anti-harassment-policies.md | 16 +- company-policies/expenses.md | 12 +- .../new-hire-orientation/README.md | 16 +- .../new-hire-orientation/bookmarks.md | 50 ++-- .../new-hire-orientation/buddy-program.md | 32 +-- .../new-hire-orientation/elevator-pitch.md | 18 +- .../new-hire-orientation/intro-open-source.md | 10 +- .../meetings-and-meeting-tools.md | 40 +-- .../new-hire-orientation/people-planning.md | 12 +- .../new-hire-orientation/security-training.md | 26 +- .../training-resources.md | 40 +-- .../video-call-best-practices.md | 36 +-- .../virtual-workplace-basics.md | 38 +-- .../prohibited-hardware-and-software.md | 18 +- company-policies/security.md | 116 ++++---- company-policies/sustainability.md | 14 +- company-policies/timekeeping-policies.md | 72 ++--- company-policies/timesheets.md | 64 ++--- employee-benefits/README.md | 44 +-- employee-benefits/canada-benefits-policy.md | 10 +- employee-benefits/canada-tech-stipend.md | 6 +- employee-benefits/on-call-stipend.md | 44 +-- employee-benefits/professional-development.md | 24 +- employee-benefits/us-tech-stipend.md | 6 +- practice-areas/README.md | 14 +- practice-areas/accessibility/README.md | 24 +- practice-areas/design-and-research/README.md | 58 ++-- practice-areas/engineering/accessibility.md | 38 +-- practice-areas/engineering/drupal/README.md | 16 +- ...drupal-contrib-first-module-development.md | 6 +- ...for-getting-the-most-out-of-open-source.md | 80 +++--- .../drupal/drupal-for-drupal-engineers.md | 16 +- .../engineering/drupal/drupal-for-everyone.md | 16 +- .../drupal/drupal-for-project-teams.md | 18 +- ...-site-contributed-vs-custom-development.md | 34 +-- .../engineering/engineering-calls.md | 24 +- practice-areas/engineering/git.md | 166 ++++++------ .../engineering/security-compliance.md | 92 +++---- .../engineering/tech-lead/README.md | 218 +++++++-------- .../engineering/text-editors-ides.md | 6 +- ...roject-support-accessibility-guidelines.md | 16 +- .../help-desk/project-support-checklist.md | 50 ++-- practice-areas/project-management/README.md | 142 +++++----- .../contractual-requirements.md | 18 +- ...al-tooling-guidelines-for-project-teams.md | 38 +-- .../project-management/growth-mindset.md | 38 +-- .../project-management/innovation.md | 28 +- .../leave-requests-and-stepping-away.md | 6 +- .../project-management/listserv-setup.md | 28 +- .../project-management/mods-and-extensions.md | 14 +- .../onboarding-new-project-team-member.md | 40 +-- .../planning-onsite-meetings.md | 16 +- .../project-management/pm-training.md | 100 +++---- .../project-management/pm-unanet-tasks.md | 12 +- .../project-management/project-calendar.md | 18 +- .../project-management/project-folder.md | 24 +- .../project-management/project-offboarding.md | 132 ++++----- .../starting-new-project.md | 74 ++--- .../team-working-agreements-instructions.md | 26 +- .../project-management/templates.md | 8 +- 105 files changed, 2011 insertions(+), 2011 deletions(-) diff --git a/about-civicactions/culture.md b/about-civicactions/culture.md index 4917fb3a9b..8528b3b6a7 100644 --- a/about-civicactions/culture.md +++ b/about-civicactions/culture.md @@ -26,13 +26,13 @@ Nobody is a perfect communicator, and we recognize that there are many "ideals" Here are some of the tools and practices we use to help us remain open with each other: -- **Slack channels and email lists** - We communicate in a group setting, reducing the need for one-on-one communications that can lead to silos or keep people out of the loop. -- **Daily scrum calls on video** - Everyday, each team member meets to report on what they did yesterday, what they plan on doing today, and whether they have any blockers. This is an opportunity to offer support and hold each other accountable. It also builds team camaraderie by having a daily forum to look at each other and connect. -- **Active listening** - Talking "at" each other doesn't always result in a shared understanding. By repeating back what you are hearing from the other person, you are able to verify that you understand them and give them a chance to correct any misunderstandings or wrong assumptions. -- **Tensions** - A tension is any issue or reflection we have shelved, buried, or simply not thought to share. Our practice at CivicActions is to recognize when we have a tension concerning a team member, and ask the person if we can share it in a safe conversation where the sole purpose is to clear the air and both parties agree to simply acknowledge the tension and then close the conversation. When we share in this objective way, we clear our minds of anything that might interfere with being able to hear what the other person is saying. When we have shared a tension we might have with someone, we can then be present to who they are in this moment, rather than the story we have been telling ourselves about them. -- **Retrospectives** - These occur at the end of each sprint on a project level, or at other milestones for any department or activity at CivicActions. It's a forum to talk about what is working, what isn't, and what we can improve. It's a safe space to discuss failure _without blame_ and to reflect on successes and celebrate team members too. We also use retrospectives for annual reviews. -- **Balance scores** - At every meeting, we each report our "balance score" -- a number from 1 to 10 that represents how well you are recognizing and honoring your priorities in your personal, work, and spiritual life. Everyone knows about the struggle for "work-life balance," and this practice is our way of empowering people to honor theirs -- with the addition of spiritual/mental health as well. A high balance score doesn't necessarily mean everything is going perfectly in your life, but it means you are honoring the priorities you have set for yourself. By hearing the balance of other team members, we can remain attuned to who might need extra support, or who is thriving and might have capacity to serve as a resource for others. You can read more about balance scores in [this blog post](https://medium.com/civicactions/improving-scrum-team-flow-on-digital-service-projects-6723d95eaad8). -- **Culture videos** - We have [several videos](https://vimeo.com/civicactions) that feature team members talking about CivicActions. It's an interesting glimpse into the different values and appreciations from our peers. We invest a lot of energy into appreciating each other and creating a company where people are free to be themselves and grow their skills by taking risks and learning from failure. +- **Slack channels and email lists** - We communicate in a group setting, reducing the need for one-on-one communications that can lead to silos or keep people out of the loop. +- **Daily scrum calls on video** - Everyday, each team member meets to report on what they did yesterday, what they plan on doing today, and whether they have any blockers. This is an opportunity to offer support and hold each other accountable. It also builds team camaraderie by having a daily forum to look at each other and connect. +- **Active listening** - Talking "at" each other doesn't always result in a shared understanding. By repeating back what you are hearing from the other person, you are able to verify that you understand them and give them a chance to correct any misunderstandings or wrong assumptions. +- **Tensions** - A tension is any issue or reflection we have shelved, buried, or simply not thought to share. Our practice at CivicActions is to recognize when we have a tension concerning a team member, and ask the person if we can share it in a safe conversation where the sole purpose is to clear the air and both parties agree to simply acknowledge the tension and then close the conversation. When we share in this objective way, we clear our minds of anything that might interfere with being able to hear what the other person is saying. When we have shared a tension we might have with someone, we can then be present to who they are in this moment, rather than the story we have been telling ourselves about them. +- **Retrospectives** - These occur at the end of each sprint on a project level, or at other milestones for any department or activity at CivicActions. It's a forum to talk about what is working, what isn't, and what we can improve. It's a safe space to discuss failure _without blame_ and to reflect on successes and celebrate team members too. We also use retrospectives for annual reviews. +- **Balance scores** - At every meeting, we each report our "balance score" -- a number from 1 to 10 that represents how well you are recognizing and honoring your priorities in your personal, work, and spiritual life. Everyone knows about the struggle for "work-life balance," and this practice is our way of empowering people to honor theirs -- with the addition of spiritual/mental health as well. A high balance score doesn't necessarily mean everything is going perfectly in your life, but it means you are honoring the priorities you have set for yourself. By hearing the balance of other team members, we can remain attuned to who might need extra support, or who is thriving and might have capacity to serve as a resource for others. You can read more about balance scores in [this blog post](https://medium.com/civicactions/improving-scrum-team-flow-on-digital-service-projects-6723d95eaad8). +- **Culture videos** - We have [several videos](https://vimeo.com/civicactions) that feature team members talking about CivicActions. It's an interesting glimpse into the different values and appreciations from our peers. We invest a lot of energy into appreciating each other and creating a company where people are free to be themselves and grow their skills by taking risks and learning from failure. ### Personal pronouns @@ -45,10 +45,10 @@ These practices won't be familiar to everyone, and it may take some time and pra **Resources** Check out the All Humans Call (AHC) slide deck on personal pronouns to learn more about: -- What are gender neutral pronouns? -- Why do personal pronouns matter in our industry? -- What to do if you mess up -- How to make a correction +- What are gender neutral pronouns? +- Why do personal pronouns matter in our industry? +- What to do if you mess up +- How to make a correction [AHC: Personal pronouns (slide deck)](https://docs.google.com/presentation/d/1v0Ak3oAL5ZrxywQUf1hioUe3BY-73IeaV1XNiAhb9UY/edit) @@ -72,13 +72,13 @@ Inclusion is a sense of belonging that allows people to fully engage and contrib Some practical tips for making inclusive spaces on your team: -- Observe your teammates' personal pronouns -- Notice who isn't speaking, and give them opportunities to contribute -- Celebrate the things your teammates do well -- Start noticing when you've made an assumption, and ask questions instead -- Practice active listening (see the previous section) -- Take time to learn more about how inequality affects people at work -- Speak up when you notice that someone is disrespected or left out +- Observe your teammates' personal pronouns +- Notice who isn't speaking, and give them opportunities to contribute +- Celebrate the things your teammates do well +- Start noticing when you've made an assumption, and ask questions instead +- Practice active listening (see the previous section) +- Take time to learn more about how inequality affects people at work +- Speak up when you notice that someone is disrespected or left out We work to model the change we want to see in the world, and that starts with how we make space for each other at work. At CivicActions, diversity, equity, inclusion, and accessibility isn't just a core part of our culture, it's also a committee. @@ -114,9 +114,9 @@ A: The most successful team members at CivicActions embody the culture and value A: We are a very supportive team and if you need help, we want you to know that there are resources available. -- If you want help with your work, your team, your project, etc: Go to your manager, your project manager, someone else on your project team, or your mentor. -- If you feel unbalanced: Go to your manager, your project manager, mentor, or PeopleOps. -- If you are being harassed or feel uncomfortable or unsafe: Go to Elizabeth or anyone else on the PeopleOps team. +- If you want help with your work, your team, your project, etc: Go to your manager, your project manager, someone else on your project team, or your mentor. +- If you feel unbalanced: Go to your manager, your project manager, mentor, or PeopleOps. +- If you are being harassed or feel uncomfortable or unsafe: Go to Elizabeth or anyone else on the PeopleOps team. ### Q: What is CivicActions doing to foster diversity? diff --git a/about-civicactions/diversity-equity-inclusion/README.md b/about-civicactions/diversity-equity-inclusion/README.md index 762f88c21d..b7ce400a45 100644 --- a/about-civicactions/diversity-equity-inclusion/README.md +++ b/about-civicactions/diversity-equity-inclusion/README.md @@ -10,7 +10,7 @@ We have a responsibility to address the inequality that permeates our lives as c ## Why DEIA is important to us -- Our **public sector clients** count on us to create equitable solutions for the diversity of the people they serve, therefore we value diverse perspectives on our team that so we can better serve the public. -- Good user experience design considers everyone. We value **diversity in user research** so that our design solutions reflect the people we serve. -- Whether it's a diversity of experiences, skill sets, approaches to problem-solving, or social identity, we believe that **team diversity and inclusion** makes us better at solving problems. -- Having diversity in our team continues to broaden our ability to represent the people and experiences that we are creating software for. +- Our **public sector clients** count on us to create equitable solutions for the diversity of the people they serve, therefore we value diverse perspectives on our team that so we can better serve the public. +- Good user experience design considers everyone. We value **diversity in user research** so that our design solutions reflect the people we serve. +- Whether it's a diversity of experiences, skill sets, approaches to problem-solving, or social identity, we believe that **team diversity and inclusion** makes us better at solving problems. +- Having diversity in our team continues to broaden our ability to represent the people and experiences that we are creating software for. diff --git a/about-civicactions/diversity-equity-inclusion/affinity-channels.md b/about-civicactions/diversity-equity-inclusion/affinity-channels.md index bd302b9468..e3822ab49b 100644 --- a/about-civicactions/diversity-equity-inclusion/affinity-channels.md +++ b/about-civicactions/diversity-equity-inclusion/affinity-channels.md @@ -20,23 +20,23 @@ Team Members who are interested may form additional unofficial private or public List of some affinity channels: -- `#parenting` (open): Parents and caregivers of children share joy and resources. Parents and their allies are welcome. -- `#ca-womxn` (open): Networking, supporting, and celebrating them/they/she/her. Individuals identifying as female, trans, gender non-conforming, and their allies are welcome. -- `#rainbow` (open): A space to have conversations related to the LGBTQ2+ community. Members of the community including allies are welcome! +- `#parenting` (open): Parents and caregivers of children share joy and resources. Parents and their allies are welcome. +- `#ca-womxn` (open): Networking, supporting, and celebrating them/they/she/her. Individuals identifying as female, trans, gender non-conforming, and their allies are welcome. +- `#rainbow` (open): A space to have conversations related to the LGBTQ2+ community. Members of the community including allies are welcome! Regional Groups: -- `#ca-california` (open): For team members located in California. -- `#ca-canada-chatter` (open): For team members located in Canada. -- `#ca-dc` (open): For team members located in DC. -- `#ca-florida` (open): For team members located in Florida. -- `#ca-mi` (open): For team members located in Michigan. -- `#ca-midwest` (open): For team members located in the Midwest area. -- `#ca-new-england` (open): For team members located in the New England area. -- `#ca-pnw` (open): For team members located in the Pacific Northwest area. -- `#ca-rockymountains` (open): For team members located in the Rocky Mountains area. -- `#ca-thesouth` (open): For team members located in the South. -- `#ca-tx` (open): For team members located in Texas. +- `#ca-california` (open): For team members located in California. +- `#ca-canada-chatter` (open): For team members located in Canada. +- `#ca-dc` (open): For team members located in DC. +- `#ca-florida` (open): For team members located in Florida. +- `#ca-mi` (open): For team members located in Michigan. +- `#ca-midwest` (open): For team members located in the Midwest area. +- `#ca-new-england` (open): For team members located in the New England area. +- `#ca-pnw` (open): For team members located in the Pacific Northwest area. +- `#ca-rockymountains` (open): For team members located in the Rocky Mountains area. +- `#ca-thesouth` (open): For team members located in the South. +- `#ca-tx` (open): For team members located in Texas. ## Who can join an affinity channel @@ -56,11 +56,11 @@ Affinity channel moderators serve as the main point of contact for team members ## How to create a new affinity channel -- Anyone at CivicActions can create a new affinity channel. Before starting a new affinity group, check the affinity channels directory to make sure a similar group does not already exist. -- Add a new channel by clicking the + next to the Slack channels list. -- Be sure to give your channel a description, and add a channel topic so people understand who it is for. -- Decide whether to make your channel private. -- Designate a point person moderator for your channel and add them to the channel topic. Be sure that moderator's understand their obligations as a channel moderator. If a person is not comfortable fulfilling all of the responsibilities of a moderator they should not take on that role. -- Do a GitHub pull request to get your channel listed on the affinity channel guidebook directory page; or if preferred, ask Alaine to add your new channel to the guidebook page. -- Announce your new channel in #general so others can join. -- If you decide that the group you want to create is not going to be open to allies, then it's not an official company affinity group and won't be included in the directory. +- Anyone at CivicActions can create a new affinity channel. Before starting a new affinity group, check the affinity channels directory to make sure a similar group does not already exist. +- Add a new channel by clicking the + next to the Slack channels list. +- Be sure to give your channel a description, and add a channel topic so people understand who it is for. +- Decide whether to make your channel private. +- Designate a point person moderator for your channel and add them to the channel topic. Be sure that moderator's understand their obligations as a channel moderator. If a person is not comfortable fulfilling all of the responsibilities of a moderator they should not take on that role. +- Do a GitHub pull request to get your channel listed on the affinity channel guidebook directory page; or if preferred, ask Alaine to add your new channel to the guidebook page. +- Announce your new channel in #general so others can join. +- If you decide that the group you want to create is not going to be open to allies, then it's not an official company affinity group and won't be included in the directory. diff --git a/about-civicactions/diversity-equity-inclusion/defining-dei.md b/about-civicactions/diversity-equity-inclusion/defining-dei.md index 1cfc41fbef..8498fb15ba 100644 --- a/about-civicactions/diversity-equity-inclusion/defining-dei.md +++ b/about-civicactions/diversity-equity-inclusion/defining-dei.md @@ -10,10 +10,10 @@ Diversity describes the range of differences within a group with regard to socia ### What we're doing to support diversity -- Refining our hiring process to actively recruit for diversity -- Promoting a space for team members to discuss and educate themselves about diversity -- Establishing guidelines for recruiting diverse groups of participants for UX research -- Participating in events that promote diversity +- Refining our hiring process to actively recruit for diversity +- Promoting a space for team members to discuss and educate themselves about diversity +- Establishing guidelines for recruiting diverse groups of participants for UX research +- Participating in events that promote diversity ## Equity @@ -23,11 +23,11 @@ Instead, equity addresses the past or present conditions that may continue to ho ### What we're doing to support equity -- Creating professional development opportunities and support for team members who have had less access to opportunities in the past -- Facilitating a culture of mentorship by [encouraging peer support](../../employee-benefits/professional-development.md#asking-a-mentor-coach-or-peer-to-help) through coworking or one-on-one check-ins -- Investing in our team's [professional development](../../employee-benefits/professional-development.md) while giving individuals the agency to choose what they'd like to learn -- Sharing knowledge within practice areas through regular skill shares and collaboration -- [Supporting distributed teams](https://medium.com/civicactions/an-open-dialogue-on-work-and-life-in-a-distributed-team-796ef88813cd) who work remotely, which allows our team members to work in locations and environments best suited to their needs and abilities +- Creating professional development opportunities and support for team members who have had less access to opportunities in the past +- Facilitating a culture of mentorship by [encouraging peer support](../../employee-benefits/professional-development.md#asking-a-mentor-coach-or-peer-to-help) through coworking or one-on-one check-ins +- Investing in our team's [professional development](../../employee-benefits/professional-development.md) while giving individuals the agency to choose what they'd like to learn +- Sharing knowledge within practice areas through regular skill shares and collaboration +- [Supporting distributed teams](https://medium.com/civicactions/an-open-dialogue-on-work-and-life-in-a-distributed-team-796ef88813cd) who work remotely, which allows our team members to work in locations and environments best suited to their needs and abilities ## Inclusion @@ -37,12 +37,12 @@ As a working group, we understand that creating an inclusive work culture is the ### What we're doing to support an inclusive team culture -- Creating space for our team to learn about gender diversity and share our personal pronouns in the workplace -- Helping new hires feel welcome through one-on-one onboarding, mentorship, and training focused on DEI -- Creating open communication with job candidates who want to learn more about the company directly from the people who work here -- Finding ways to promote a flat organizational culture -- Creating opportunities for CivicActioners to form relationships on pod calls that aren't work-focused -- Offering Slack channels for various affinity groups — spaces where folks can openly discuss issues and causes that are important to them +- Creating space for our team to learn about gender diversity and share our personal pronouns in the workplace +- Helping new hires feel welcome through one-on-one onboarding, mentorship, and training focused on DEI +- Creating open communication with job candidates who want to learn more about the company directly from the people who work here +- Finding ways to promote a flat organizational culture +- Creating opportunities for CivicActioners to form relationships on pod calls that aren't work-focused +- Offering Slack channels for various affinity groups — spaces where folks can openly discuss issues and causes that are important to them ## Accessibility @@ -50,8 +50,8 @@ There are many [definitions for accessibility](https://en.wikipedia.org/wiki/Soc ### What we're doing to support an accessible team culture -- [Accessibility is part of our company culture](../culture.md#accessibility) -- CivicActions has an [Accessibility Practice Area](../../practice-areas/accessibility/README.md) and a [dedicated sub-site](https://accessibility.civicactions.com/) -- All new staff are given onboarding on accessibility issues when they join the company -- We are finding ways to think more about accessibility barriers in our hiring process and internal communications -- Our team is encouraged to contribute and incorporate accessibility into their work +- [Accessibility is part of our company culture](../culture.md#accessibility) +- CivicActions has an [Accessibility Practice Area](../../practice-areas/accessibility/README.md) and a [dedicated sub-site](https://accessibility.civicactions.com/) +- All new staff are given onboarding on accessibility issues when they join the company +- We are finding ways to think more about accessibility barriers in our hiring process and internal communications +- Our team is encouraged to contribute and incorporate accessibility into their work diff --git a/about-civicactions/diversity-equity-inclusion/deia-get-involved.md b/about-civicactions/diversity-equity-inclusion/deia-get-involved.md index 701acf574f..d8f6dd03a7 100644 --- a/about-civicactions/diversity-equity-inclusion/deia-get-involved.md +++ b/about-civicactions/diversity-equity-inclusion/deia-get-involved.md @@ -19,5 +19,5 @@ Not everyone is at the same level of familiarity or comfort with DEIA topics, an ### DEIA Committee responsibilities -- Receive and understand DEIA survey brief, areas of focus, goals, initiatives and how we are progressing towards our goals. -- Partner with the People Department and provide feedback and additional insights that could help us attain our DEIA goals and/or initiatives. +- Receive and understand DEIA survey brief, areas of focus, goals, initiatives and how we are progressing towards our goals. +- Partner with the People Department and provide feedback and additional insights that could help us attain our DEIA goals and/or initiatives. diff --git a/about-this-guidebook/editing-the-guidebook.md b/about-this-guidebook/editing-the-guidebook.md index 1bc0dbe8f4..72bf592b9c 100644 --- a/about-this-guidebook/editing-the-guidebook.md +++ b/about-this-guidebook/editing-the-guidebook.md @@ -20,53 +20,53 @@ New employees receive an email invite to join the CivicActions account. If you m ### Editing an existing page -- Go to the guidebook repository (also known as the repo): https://github.com/CivicActions/guidebook. -- Open one of these folders: - - about-CivicActions - - employee-benefits - - company-policies - - common-practices-tools - - practice-areas - - about-this-guidebook -- Click on the page you want to edit. -- Click the pencil icon to edit. -- Make your changes using markdown. -- Click the **Preview tab** to make sure everything looks right. +- Go to the guidebook repository (also known as the repo): https://github.com/CivicActions/guidebook. +- Open one of these folders: + - about-CivicActions + - employee-benefits + - company-policies + - common-practices-tools + - practice-areas + - about-this-guidebook +- Click on the page you want to edit. +- Click the pencil icon to edit. +- Make your changes using markdown. +- Click the **Preview tab** to make sure everything looks right. ### Creating a new page -- Go to the guidebook repository (also known as the repo): https://github.com/CivicActions/guidebook. -- Open one of these existing folders in the repo (do not create a new folder): - - about-CivicActions - - employee-benefits - - company-policies - - common-practices-tools - - practice-areas - - about-this-guidebook -- Click Add file > Create new file. +- Go to the guidebook repository (also known as the repo): https://github.com/CivicActions/guidebook. +- Open one of these existing folders in the repo (do not create a new folder): + - about-CivicActions + - employee-benefits + - company-policies + - common-practices-tools + - practice-areas + - about-this-guidebook +- Click Add file > Create new file. ![Screenshot of GitHub directory with dropdown menu with two items: Create new file and Upload file.](../assets/images/1-Create-new-file.png) -- Name your file, ending with the extension .md. +- Name your file, ending with the extension .md. ![Screenshot of new GitHub file field where you enter the name of the new file.](../assets/images/2-Name-file.png) -- Add your content. -- Click the **Preview** tab to make sure everything looks right. +- Add your content. +- Click the **Preview** tab to make sure everything looks right. ## Step 3: Save your changes When you are ready to save your changes (known in Gitspeak as "make a commit"), you'll see three fields at the bottom of the editing screen. All of these fields are optional, with default values. In most cases it's fine to leave the defaults. -- The commit title: By default this is something like "Update (filename)". You can leave this as is. If you want to be more precise, keep it short. -- Extended description: Explain your changes, if you wish. -- The branch name: By default this will be a new branch. +- The commit title: By default this is something like "Update (filename)". You can leave this as is. If you want to be more precise, keep it short. +- Extended description: Explain your changes, if you wish. +- The branch name: By default this will be a new branch. After you commit, you will be asked if you want to create a new pull request with the branch you created. You'll again be presented with a few fields, which you can generally leave as is. -- The PR title: By default it is the title of your last commit. -- Extended description: This also draws from your last commit. -- The right sidebar: You can assign your pull request to someone on the team (someone you think may want to review your edits). +- The PR title: By default it is the title of your last commit. +- Extended description: This also draws from your last commit. +- The right sidebar: You can assign your pull request to someone on the team (someone you think may want to review your edits). When you save your changes, Git will create a new branch for your change using the default format (username)-patch-1. This branch is a copy of the entire guidebook. Any changes you make in this new branch do not affect the master branch for the guidebook. Your changes take effect when the branch is merged (Step 7). @@ -80,9 +80,9 @@ Click **Propose changes**. You've just made a commit. After you've made your commit, Git will ask if you want to create a new pull request with the new branch you just created. **You need to create a pull request before your changes can be reviewed**. You'll again be presented with a few fields, which you can generally leave as is. -- The PR title: By default it is the title of your last commit. -- Extended description: This also draws from your last commit. -- The right sidebar: You can assign your pull request to someone on the team (someone you think may want to review your edits). If you think that certain individuals may have particular subject matter expertise or authority on the topic, you can also assign them directly via the "Reviewers" section. +- The PR title: By default it is the title of your last commit. +- Extended description: This also draws from your last commit. +- The right sidebar: You can assign your pull request to someone on the team (someone you think may want to review your edits). If you think that certain individuals may have particular subject matter expertise or authority on the topic, you can also assign them directly via the "Reviewers" section. If you are only changing **one** page, click **Create pull request**. If you are changing more than one page, don't create the PR quite yet. @@ -104,15 +104,15 @@ If you need help fixing errors, message the [#docs](https://civicactions.slack.c If you are adding new content or changing the title (H1) of an existing page, you will need to update the settings file containing the navigation labels. If you are not sure where to place your content in the navigation, start a conversation in [#docs](https://civicactions.slack.com/messages/docs/) in Slack. -- Go to the guidebook repo: https://github.com/CivicActions/guidebook. -- Click the .config folder to open. -- Click the mkdocs.yml file to open. -- Click the pencil icon to edit the file. -- Scroll down to the navigation section ("nav:") and locate either: - - the line you want to change, or - - where you will insert a new line to add the navigation label for your new content. - - If you are adding a new page, use the format: navigation label: file name (with .md). -- Save your commit and create the pull request. Note the PR number of the content PR in the description field so the reviewer can see the changes in the content. +- Go to the guidebook repo: https://github.com/CivicActions/guidebook. +- Click the .config folder to open. +- Click the mkdocs.yml file to open. +- Click the pencil icon to edit the file. +- Scroll down to the navigation section ("nav:") and locate either: + - the line you want to change, or + - where you will insert a new line to add the navigation label for your new content. + - If you are adding a new page, use the format: navigation label: file name (with .md). +- Save your commit and create the pull request. Note the PR number of the content PR in the description field so the reviewer can see the changes in the content. The PR will be reviewed by a team member before being merged. diff --git a/about-this-guidebook/guidebook-governance.md b/about-this-guidebook/guidebook-governance.md index db3948177a..a46ddd17ae 100644 --- a/about-this-guidebook/guidebook-governance.md +++ b/about-this-guidebook/guidebook-governance.md @@ -16,7 +16,7 @@ These teams are listed on GitHub as [subteams](https://github.com/orgs/CivicActi The [CODEOWNERS](https://github.com/civicactions/guidebook/blob/master/CODEOWNERS) file in the top level of this repo: -- Maps the governance of subdirectories to their respective GitHub teams and CivicActions practice areas. -- Automatically assigns pull requests to that team for review, when a PR is submitted that. +- Maps the governance of subdirectories to their respective GitHub teams and CivicActions practice areas. +- Automatically assigns pull requests to that team for review, when a PR is submitted that. GitHub team management is an ongoing responsibility of the Docs working group. They can add someone to a team via the [subteam page](https://github.com/orgs/CivicActions/teams/civicactions-team/teams) by clicking **Add a member**. diff --git a/about-this-guidebook/markdown-for-guidebook.md b/about-this-guidebook/markdown-for-guidebook.md index 50cce7cae7..311aba6bee 100644 --- a/about-this-guidebook/markdown-for-guidebook.md +++ b/about-this-guidebook/markdown-for-guidebook.md @@ -14,21 +14,21 @@ There's a great tutorial [on the Commonmark website](http://commonmark.org/help/ ## Common markdown errors to avoid -- You need a blank line before every "block" of text. "Blocks" include paragraphs, headings, lists, code blocks, blockquotes, etc. -- You need a blank line at the end of each file. -- Headings (#, ##, ###, etc.) must increment correctly. You can't go from # (h1) to ### (h3). +- You need a blank line before every "block" of text. "Blocks" include paragraphs, headings, lists, code blocks, blockquotes, etc. +- You need a blank line at the end of each file. +- Headings (#, ##, ###, etc.) must increment correctly. You can't go from # (h1) to ### (h3). ## Format auto-correct -- Many common Markdown formatting issues will be automatically corrected after you submit your Pull Request. -- This applies the FOSS tool [Prettier](https://prettier.io/) using the default configuration, which is our canonical standard. +- Many common Markdown formatting issues will be automatically corrected after you submit your Pull Request. +- This applies the FOSS tool [Prettier](https://prettier.io/) using the default configuration, which is our canonical standard. ## Markdown checking (linter) We use for additional linting/checking our markdown syntax as well as making suggestions around common readability, language and grammar issues. -- The [remarkrc.problem file](https://github.com/CivicActions/guidebook/blob/master/.config/remark/remarkrc.problem) shows a list of all the rules being enforced. -- The [remarkrc.suggestion file](https://github.com/CivicActions/guidebook/blob/master/.config/remark/remarkrc.suggestion) shows a list of all rules used to give suggestions. +- The [remarkrc.problem file](https://github.com/CivicActions/guidebook/blob/master/.config/remark/remarkrc.problem) shows a list of all the rules being enforced. +- The [remarkrc.suggestion file](https://github.com/CivicActions/guidebook/blob/master/.config/remark/remarkrc.suggestion) shows a list of all rules used to give suggestions. This linter is run by [GitHub Actions](automatic-checking.md) with each pull request and code merge, and will automatically post a pull request review indicating problems and suggestions. You can also access the log of problems and suggestions from the GitHub Actions check details link. @@ -38,12 +38,12 @@ Finally, the mkdocs command may identify broken links or other issues in the pul You can check that your markdown complies with the retext and remark locally: -- Install node.js if you don't have it already: (or use a package manager). -- Install yarn: (various options to install, could also use a package manager). -- Open a terminal and `cd` to your Git root. -- Run `yarn install` to install the dependencies. -- Run `./node_modules/.bin/gulp` (you can also pass in `--path=` to a specific file to limit tests to just that). -- Run `./node_modules/.bin/prettier --write ` to automatically format a file. +- Install node.js if you don't have it already: (or use a package manager). +- Install yarn: (various options to install, could also use a package manager). +- Open a terminal and `cd` to your Git root. +- Run `yarn install` to install the dependencies. +- Run `./node_modules/.bin/gulp` (you can also pass in `--path=` to a specific file to limit tests to just that). +- Run `./node_modules/.bin/prettier --write ` to automatically format a file. ## Editors diff --git a/about-this-guidebook/why-guidebook-is-open.md b/about-this-guidebook/why-guidebook-is-open.md index 80730167f1..1c2e00faf0 100644 --- a/about-this-guidebook/why-guidebook-is-open.md +++ b/about-this-guidebook/why-guidebook-is-open.md @@ -8,9 +8,9 @@ Working in the open embodies the [CivicActions culture](../about-civicactions/cu We've made our guidebook open and available publicly so that: -- Current employees and new hires can access it from wherever they are -- Potential job candidates can learn what we're about and why it's awesome to work here -- We can showcase our [commitment to accessibility](https://accessibility.civicactions.com/) (and work with the community to fix things when they are not accessible) +- Current employees and new hires can access it from wherever they are +- Potential job candidates can learn what we're about and why it's awesome to work here +- We can showcase our [commitment to accessibility](https://accessibility.civicactions.com/) (and work with the community to fix things when they are not accessible) Most importantly, this guidebook is open because we believe that the power of transparency and collaboration leads to the best outcomes. diff --git a/about-this-guidebook/writing-style-guide.md b/about-this-guidebook/writing-style-guide.md index 8b31cbe680..b5cbae0524 100644 --- a/about-this-guidebook/writing-style-guide.md +++ b/about-this-guidebook/writing-style-guide.md @@ -20,9 +20,9 @@ We use sentence case for our titles and headings. When using sentence case, we c Examples -- Site building using Drupal -- Engineer's role in client relationships -- Accessibility: Everyone has a role +- Site building using Drupal +- Engineer's role in client relationships +- Accessibility: Everyone has a role ## Automated suggestions for improvement @@ -30,4 +30,4 @@ The [GitHub Actions build](automatic-checking.md) outputs a list of suggestions ## Specific terms -- Specify Free/Libre Open Source Software, which can be shortened to FLOSS. Do not use just "open source software". See [Richard Stallman's explanation](https://www.gnu.org/philosophy/floss-and-foss.en.html) if you want to know more. +- Specify Free/Libre Open Source Software, which can be shortened to FLOSS. Do not use just "open source software". See [Richard Stallman's explanation](https://www.gnu.org/philosophy/floss-and-foss.en.html) if you want to know more. diff --git a/common-practices-tools/agile/README.md b/common-practices-tools/agile/README.md index 39eabb71f6..07d14b9dfd 100644 --- a/common-practices-tools/agile/README.md +++ b/common-practices-tools/agile/README.md @@ -6,9 +6,9 @@ title: Agile overview CivicActions uses Agile practices. -- Read the [Agile Manifesto](http://agilemanifesto.org/) statement -- Watch this short [Agile video](https://youtu.be/AsFMHnSfI2I) or this more detailed [Agile video](https://youtu.be/Z9QbYZh1YXY) -- Check out [Technologists for the Public Good](https://www.publicgood.tech/) (previously Agile Gov Leadership) -- Skim CivicActions blog posts tagged as [Agile Gov](https://medium.com/civicactions/tagged/agile-government). -- For a deeper dive, visit our [agile-practices documentation](agile-practices.md) and the pages within this section -- Check out the [CivicActions project playbook](https://trello.com/b/qyI4wa18/template-civicactions-project-playbook) +- Read the [Agile Manifesto](http://agilemanifesto.org/) statement +- Watch this short [Agile video](https://youtu.be/AsFMHnSfI2I) or this more detailed [Agile video](https://youtu.be/Z9QbYZh1YXY) +- Check out [Technologists for the Public Good](https://www.publicgood.tech/) (previously Agile Gov Leadership) +- Skim CivicActions blog posts tagged as [Agile Gov](https://medium.com/civicactions/tagged/agile-government). +- For a deeper dive, visit our [agile-practices documentation](agile-practices.md) and the pages within this section +- Check out the [CivicActions project playbook](https://trello.com/b/qyI4wa18/template-civicactions-project-playbook) diff --git a/common-practices-tools/agile/backlog-refinement.md b/common-practices-tools/agile/backlog-refinement.md index 87d48939e7..9940cea143 100644 --- a/common-practices-tools/agile/backlog-refinement.md +++ b/common-practices-tools/agile/backlog-refinement.md @@ -30,4 +30,4 @@ Backlog Refinement sessions are an important part of preparation for [Sprint Pla ## Additional Resources -- [Scrum Training Series Video](http://scrumtrainingseries.com/BacklogRefinementMeeting/BacklogRefinementMeeting.htm) +- [Scrum Training Series Video](http://scrumtrainingseries.com/BacklogRefinementMeeting/BacklogRefinementMeeting.htm) diff --git a/common-practices-tools/agile/daily-scrum-calls.md b/common-practices-tools/agile/daily-scrum-calls.md index 75563c3935..8ba842ad15 100644 --- a/common-practices-tools/agile/daily-scrum-calls.md +++ b/common-practices-tools/agile/daily-scrum-calls.md @@ -16,11 +16,11 @@ The meeting participants should be any members of the project team committed to The daily scrum meeting should be scheduled for the same time each day whenever possible. The Scrum Master should facilitate the meeting, and the total meeting time should be limited to 15 minutes. Since the CivicActions workforce is fully distributed, best practice is to have each person enable his/her camera for the entire meeting and to have microphone muted when not speaking. One person "checks in" by answering the following talking points: -- Give your Balance Score -- What you worked on yesterday -- What you plan on working on next -- Note any issues blocking progress on your work -- Verbally pass to another team member to do the same +- Give your Balance Score +- What you worked on yesterday +- What you plan on working on next +- Note any issues blocking progress on your work +- Verbally pass to another team member to do the same During check ins, it is possible there will be topics uncovered that require additional conversation. Best practice is to have the Scrum Master note these topics for an "after-meeting" so they can be discussed later with only the relevant participants present. This practice saves other team members from listening to conversations that are not relevant to their work. @@ -34,4 +34,4 @@ The daily scrum meeting is useful in determining how well the team is progressin ## Additional Resources -- [Scrum Training Series Video](http://scrumtrainingseries.com/DailyScrumMeeting/DailyScrumMeeting.htm) +- [Scrum Training Series Video](http://scrumtrainingseries.com/DailyScrumMeeting/DailyScrumMeeting.htm) diff --git a/common-practices-tools/agile/sprint-cycle.md b/common-practices-tools/agile/sprint-cycle.md index bf765c6916..da08cce1b2 100644 --- a/common-practices-tools/agile/sprint-cycle.md +++ b/common-practices-tools/agile/sprint-cycle.md @@ -10,20 +10,20 @@ At CivicActions, the most common approach for accomplishing large-scale work is The process details included below are especially useful for complex projects with timelines spanning 1 month or more, but have also shown to be very useful in quick-turnaround situations like proposal preparation and 1-day challenges. -- Prioritize stories -- Prepare stories for development - - Decompose into development tasks - - Estimate tasks - - Define acceptance criteria -- Implement story solutions -- Review/test implementation -- Demo/validate with users -- Repeat and repeat +- Prioritize stories +- Prepare stories for development + - Decompose into development tasks + - Estimate tasks + - Define acceptance criteria +- Implement story solutions +- Review/test implementation +- Demo/validate with users +- Repeat and repeat ### Practices (aka Ceremonies) -- [Backlog Refinement](backlog-refinement.md) -- [Sprint Planning Meetings](sprint-planning-meetings.md) -- [Daily Scrum Calls](daily-scrum-calls.md) -- [Sprint Demo (Review)](sprint-demo.md) -- [Sprint Retrospectives](sprint-retrospectives.md) +- [Backlog Refinement](backlog-refinement.md) +- [Sprint Planning Meetings](sprint-planning-meetings.md) +- [Daily Scrum Calls](daily-scrum-calls.md) +- [Sprint Demo (Review)](sprint-demo.md) +- [Sprint Retrospectives](sprint-retrospectives.md) diff --git a/common-practices-tools/agile/sprint-demo.md b/common-practices-tools/agile/sprint-demo.md index 55ac30fee3..758ddc9505 100644 --- a/common-practices-tools/agile/sprint-demo.md +++ b/common-practices-tools/agile/sprint-demo.md @@ -30,4 +30,4 @@ Once the project team member has demonstrated all of his/her completed work, the ## Additional Resources -- [Scrum Training Series Video](http://scrumtrainingseries.com/SprintReviewMeeting/SprintReviewMeeting.htm) +- [Scrum Training Series Video](http://scrumtrainingseries.com/SprintReviewMeeting/SprintReviewMeeting.htm) diff --git a/common-practices-tools/agile/sprint-planning-meetings.md b/common-practices-tools/agile/sprint-planning-meetings.md index d724e370de..2f79177071 100644 --- a/common-practices-tools/agile/sprint-planning-meetings.md +++ b/common-practices-tools/agile/sprint-planning-meetings.md @@ -43,5 +43,5 @@ The Sprint Planning Meeting is arguably the most important meeting of a sprint c ## Additional Resources -- [Scrum Training Series Video](http://scrumtrainingseries.com/SprintPlanningMeeting/SprintPlanningMeeting.htm) -- [A Sprint Planning Cheat Sheet](https://www.leadingagile.com/simple-cheat-sheet-to-sprint-planning-meeting/) +- [Scrum Training Series Video](http://scrumtrainingseries.com/SprintPlanningMeeting/SprintPlanningMeeting.htm) +- [A Sprint Planning Cheat Sheet](https://www.leadingagile.com/simple-cheat-sheet-to-sprint-planning-meeting/) diff --git a/common-practices-tools/agile/sprint-retrospectives.md b/common-practices-tools/agile/sprint-retrospectives.md index 3c76756356..a9c5b83355 100644 --- a/common-practices-tools/agile/sprint-retrospectives.md +++ b/common-practices-tools/agile/sprint-retrospectives.md @@ -21,13 +21,13 @@ Depending on the project dynamics, you may choose to have an internal retrospect The Scrum Master facilitates the sprint retrospective meeting and may employ a variety of approaches in order to generate discussion. The time box for a sprint retrospective is typically 60 to 90 minutes. The standard retrospective meeting can be reduced down to these main objectives: -- Identify & discuss what worked in the sprint so that the team can continue to do it -- Identify & discuss what did not work in the sprint so that the team can improve in the next sprint +- Identify & discuss what worked in the sprint so that the team can continue to do it +- Identify & discuss what did not work in the sprint so that the team can improve in the next sprint In addition to the above, a CivicActions retrospective meeting also includes these elements: -- Appreciation of team members and their efforts -- Celebrating successes and high points of the sprint +- Appreciation of team members and their efforts +- Celebrating successes and high points of the sprint The most popular method used at CivicActions is the use of a Trello board to capture input simultaneously from all team members. Copy the [Retrospective Template](https://trello.com/b/jG9U4I6l) Trello board of your choice and follow the checklist located in the Trello card titled "Agenda" in the first column of the board. The checklist provides a step-by-step guide to facilitate the retrospective meeting. Other retrospective formats can be found at the [Retrospective Wiki](http://retrospectivewiki.org/index.php?title=Retrospective_Plans), and you are encouraged to try some of them in order to keep the retrospective process interesting and the participants engaged. You may find that some formats work well for certain projects/teams and others do not. diff --git a/common-practices-tools/agile/tickets-cards.md b/common-practices-tools/agile/tickets-cards.md index 87cddaa73b..0a2c85bf60 100644 --- a/common-practices-tools/agile/tickets-cards.md +++ b/common-practices-tools/agile/tickets-cards.md @@ -14,48 +14,48 @@ As they are prioritized, a group of user stories also can form an epic. ## Who creates tickets or cards -- Product Owners -- Product Manager -- Project Managers -- Scrum Masters -- Engineers -- UX/Design Team +- Product Owners +- Product Manager +- Project Managers +- Scrum Masters +- Engineers +- UX/Design Team ## User story -- Most tickets should contain a user story -- The structure of a user story is: As a(n) **X** I want to **Y** so that **Z** (outcome) -- Describes the **user need** for the work to be done -- Example: As an anonymous user, I want to see the latest news articles on the homepage so that I do not have to view older articles that I may have already read. -- Avoid more than one action per user story. Red flags would be commas and "ands". Consider splitting actions into multiple tickets. +- Most tickets should contain a user story +- The structure of a user story is: As a(n) **X** I want to **Y** so that **Z** (outcome) +- Describes the **user need** for the work to be done +- Example: As an anonymous user, I want to see the latest news articles on the homepage so that I do not have to view older articles that I may have already read. +- Avoid more than one action per user story. Red flags would be commas and "ands". Consider splitting actions into multiple tickets. ## Implementation plan -- The plan has notes that explain how and where to start -- Helps if another engineer has to pick up your ticket -- Often these plans/notes are in the comments field on a Jira ticket +- The plan has notes that explain how and where to start +- Helps if another engineer has to pick up your ticket +- Often these plans/notes are in the comments field on a Jira ticket ## User Acceptance Tests (UAT) -- Explains how we validate that this ticket or card works -- Written in a language anyone can understand -- Explains what the ticket will not do as well -- Acceptance Testing is the process that verifies if the installed piece of code or software works as designed for the user -- Ideally the Product Owner (PO) writes the Acceptance Test for a piece of work -- Testing with users is an important factor in ensuring the work is performing/created as expected +- Explains how we validate that this ticket or card works +- Written in a language anyone can understand +- Explains what the ticket will not do as well +- Acceptance Testing is the process that verifies if the installed piece of code or software works as designed for the user +- Ideally the Product Owner (PO) writes the Acceptance Test for a piece of work +- Testing with users is an important factor in ensuring the work is performing/created as expected ## QA tests -- Written step-by-step so that anyone can pass/fail the test -- The PO will also run through the same test -- It will also explain the expected results -- Contains specific directions or steps a tester can follow that ensure what was developed produces what the engineer intended +- Written step-by-step so that anyone can pass/fail the test +- The PO will also run through the same test +- It will also explain the expected results +- Contains specific directions or steps a tester can follow that ensure what was developed produces what the engineer intended ## Estimates -- Every ticket must be estimable -- Estimate tickets at the beginning of a sprint -- Co-working encouraged! -- Track your time daily -- Estimates should consider time for QA (on average +20%) -- Projects use story points for estimating +- Every ticket must be estimable +- Estimate tickets at the beginning of a sprint +- Co-working encouraged! +- Track your time daily +- Estimates should consider time for QA (on average +20%) +- Projects use story points for estimating diff --git a/common-practices-tools/balance-scores.md b/common-practices-tools/balance-scores.md index 3738294df7..c4283a0f97 100644 --- a/common-practices-tools/balance-scores.md +++ b/common-practices-tools/balance-scores.md @@ -6,11 +6,11 @@ title: Balance scores ## Talking points -- Explain what a balance score is -- Balance between life - work - health / spiritual - professional - personal -- When we indicate what our score is -- How we use balance scores / purpose -- The scale is 1 to 10 +- Explain what a balance score is +- Balance between life - work - health / spiritual - professional - personal +- When we indicate what our score is +- How we use balance scores / purpose +- The scale is 1 to 10 ## Benefits diff --git a/common-practices-tools/best-practices-for-managers-and-team-members.md b/common-practices-tools/best-practices-for-managers-and-team-members.md index a804387d94..36667ff5eb 100644 --- a/common-practices-tools/best-practices-for-managers-and-team-members.md +++ b/common-practices-tools/best-practices-for-managers-and-team-members.md @@ -8,29 +8,29 @@ The following are suggestions for activities that can be helpful for managers, t ## Manager on the same project -- Review project roles with the team member and how project interactions occur (you can also reference the project team working agreement). It usually happens in onboarding. -- Be transparent with what "hat" you wear in an interaction where needed. -- Encourage and support the team members to share any concerns about the project and help bring them up in the project. -- Don't focus on the project in every 1:1 (one-on-one). Try a cadence of at least one 1:1 every other month dedicated to career growth, and tailor it as needed. You can discuss prodev, goals, energy gains/drains, work-life balance, etc. -- Figure out a balance between what is best for the project and the team member. Look into ways to align them. +- Review project roles with the team member and how project interactions occur (you can also reference the project team working agreement). It usually happens in onboarding. +- Be transparent with what "hat" you wear in an interaction where needed. +- Encourage and support the team members to share any concerns about the project and help bring them up in the project. +- Don't focus on the project in every 1:1 (one-on-one). Try a cadence of at least one 1:1 every other month dedicated to career growth, and tailor it as needed. You can discuss prodev, goals, energy gains/drains, work-life balance, etc. +- Figure out a balance between what is best for the project and the team member. Look into ways to align them. ## Manager not on the same project -- Organize a regular 1:1 or slack check-in with the project tech, lead/team tech lead, or project manager to discuss and share feedback about a team member. Try a cadence of at least every two/three months. -- Ask for feedback from leads, project managers, and other team members about a member's performance, areas for improvement, and so on. Share those with the team members in a supportive manner. -- If the client permits, find a way to attend sprint demos/iteration reviews to see a team member's presentation. Ask, as needed, project and product managers about sprint demos/iteration reviews and if they have any specific feedback. Where government background checks are required to work on a project, be prepared for permission not to be granted. -- Look for appreciation for the team member and note it down for future reference. It would help if you shared/discussed this appreciation with the team members. -- Discuss project concerns with leads/project managers to figure out ways in which you can support the project or the team member. +- Organize a regular 1:1 or slack check-in with the project tech, lead/team tech lead, or project manager to discuss and share feedback about a team member. Try a cadence of at least every two/three months. +- Ask for feedback from leads, project managers, and other team members about a member's performance, areas for improvement, and so on. Share those with the team members in a supportive manner. +- If the client permits, find a way to attend sprint demos/iteration reviews to see a team member's presentation. Ask, as needed, project and product managers about sprint demos/iteration reviews and if they have any specific feedback. Where government background checks are required to work on a project, be prepared for permission not to be granted. +- Look for appreciation for the team member and note it down for future reference. It would help if you shared/discussed this appreciation with the team members. +- Discuss project concerns with leads/project managers to figure out ways in which you can support the project or the team member. ## Team member on the same project -- You should discuss project roles with your manager and how project interactions occur (you can refer to the project team working agreement). -- Share concerns about the project and brainstorm ways to resolve them. -- Focus on more than the project in 1:1s. Discuss your prodev, goals, energy gains/drains, work-life balance, etc. -- Share how you would like your career to grow and what support you would like to receive. +- You should discuss project roles with your manager and how project interactions occur (you can refer to the project team working agreement). +- Share concerns about the project and brainstorm ways to resolve them. +- Focus on more than the project in 1:1s. Discuss your prodev, goals, energy gains/drains, work-life balance, etc. +- Share how you would like your career to grow and what support you would like to receive. ## Team member not on the same project -- Collect feedback from team members, peers, and project managers about your performance, areas of improvement, and so on. Share those with your manager so they can find ways to support you as needed. -- Share your project work with your manager and any appreciation you received. -- Share/raise project concerns and ask whether you want intervention or escalation. +- Collect feedback from team members, peers, and project managers about your performance, areas of improvement, and so on. Share those with your manager so they can find ways to support you as needed. +- Share your project work with your manager and any appreciation you received. +- Share/raise project concerns and ask whether you want intervention or escalation. diff --git a/common-practices-tools/contribution/contrib-first.md b/common-practices-tools/contribution/contrib-first.md index 697bc0314c..f7174240c4 100644 --- a/common-practices-tools/contribution/contrib-first.md +++ b/common-practices-tools/contribution/contrib-first.md @@ -8,32 +8,32 @@ It is a best practice to consider first if we are building something that could ## Rationale for contrib first -- **Fiscal responsibility** - Building it and contributing it means that other government agencies will never have to pay to build the same thing twice. This helps agencies comply with Federal Source Code Policy: Achieving Efficiency, Transparency, and Innovation through Reusable and Open Source Software [OMB Memorandum M-16-21](https://obamawhitehouse.archives.gov/sites/default/files/omb/memoranda/2016/m_16_21.pdf) -- **Reusability** - CivicActions other clients and the public at large can benefit from work that was already done. -- **Security** - Contributing our work to an open source project like Drupal means it may receive security coverage by the Drupal security team and the public. It is made more secure by getting more eyes on the code and more users surfacing any issues. -- **Avoiding the gift that never happens** - Clients are not typically supportive of taking working local software that was already built for them and in use by them, and then paying to move or refactor that software to become open source. The benefit is too small for the cost. By building it as contributed code first, there is no extra cost. -- **Development happens in the open** - The issues are public. The commits are public. Everyone can contribute improvements. -- **Reliability** - A solution built for contribution is often better designed, and better documented than a local solution meant to "just get it done". By putting our company and personal names on it publicly we commit to a quality product. Releasing a FOSS solution also increases the number of testers and edge cases that can surface and reduce bugs in the code. -- **Scalability** - Contributed FOSS is more scalable than one-off solutions and can grow with the power of the FOSS community. -- **Visibility** - CivicActions, our developers and clients earn positive representation as technology leaders and contributors. -- **Economy of tests** - Unit, Kernel and Functional tests for the module are run on the pipeline on Drupal.org. This translates into savings because they not slowing down custom tests running on client servers (human time savings). They run when the module is updated, not every time custom tests run (server cost savings). -- **Digital Public Goods** - We know that contributing to the digital commons helps everyone. We know that we need to contribute to [digital publid goods](https://en.wikipedia.org/wiki/Digital_public_goods) and not simply use them. +- **Fiscal responsibility** - Building it and contributing it means that other government agencies will never have to pay to build the same thing twice. This helps agencies comply with Federal Source Code Policy: Achieving Efficiency, Transparency, and Innovation through Reusable and Open Source Software [OMB Memorandum M-16-21](https://obamawhitehouse.archives.gov/sites/default/files/omb/memoranda/2016/m_16_21.pdf) +- **Reusability** - CivicActions other clients and the public at large can benefit from work that was already done. +- **Security** - Contributing our work to an open source project like Drupal means it may receive security coverage by the Drupal security team and the public. It is made more secure by getting more eyes on the code and more users surfacing any issues. +- **Avoiding the gift that never happens** - Clients are not typically supportive of taking working local software that was already built for them and in use by them, and then paying to move or refactor that software to become open source. The benefit is too small for the cost. By building it as contributed code first, there is no extra cost. +- **Development happens in the open** - The issues are public. The commits are public. Everyone can contribute improvements. +- **Reliability** - A solution built for contribution is often better designed, and better documented than a local solution meant to "just get it done". By putting our company and personal names on it publicly we commit to a quality product. Releasing a FOSS solution also increases the number of testers and edge cases that can surface and reduce bugs in the code. +- **Scalability** - Contributed FOSS is more scalable than one-off solutions and can grow with the power of the FOSS community. +- **Visibility** - CivicActions, our developers and clients earn positive representation as technology leaders and contributors. +- **Economy of tests** - Unit, Kernel and Functional tests for the module are run on the pipeline on Drupal.org. This translates into savings because they not slowing down custom tests running on client servers (human time savings). They run when the module is updated, not every time custom tests run (server cost savings). +- **Digital Public Goods** - We know that contributing to the digital commons helps everyone. We know that we need to contribute to [digital publid goods](https://en.wikipedia.org/wiki/Digital_public_goods) and not simply use them. ## Examples of FOSS CivicActions built as Contrib First -- [Allow Only One](https://www.drupal.org/project/allow_only_one) -- [Codit: Batch Operations](https://www.drupal.org/project/codit_batch_operations) -- [Codit: Menu Tools](https://www.drupal.org/project/codit_menu_tools) -- [Content Model & Site Documentation](https://www.drupal.org/project/content_model_documentation) -- [Drupal Knowledge Archive Network (DKAN Open Data Portal)](https://github.com/GetDKAN/dkan) - - [CMSDS Open Data Components](https://github.com/GetDKAN/cmsds-open-data-components) -- [Drydock Cloud](https://github.com/drydockcloud) -- [Entity Field Fetch field](https://www.drupal.org/project/entity_field_fetch) -- [GovDelivery Bulletins](https://www.drupal.org/project/govdelivery_bulletins) -- [Mermaid Diagram Field](https://www.drupal.org/project/mermaid_diagram_field) -- [Node Link Report](https://www.drupal.org/project/node_link_report) -- [Open Accessibility Conformance Report](https://github.com/GSA/openacr) -- [Post API](https://www.drupal.org/project/post_api) -- [Vertex AI Search](https://www.drupal.org/project/vertex_ai_search) +- [Allow Only One](https://www.drupal.org/project/allow_only_one) +- [Codit: Batch Operations](https://www.drupal.org/project/codit_batch_operations) +- [Codit: Menu Tools](https://www.drupal.org/project/codit_menu_tools) +- [Content Model & Site Documentation](https://www.drupal.org/project/content_model_documentation) +- [Drupal Knowledge Archive Network (DKAN Open Data Portal)](https://github.com/GetDKAN/dkan) + - [CMSDS Open Data Components](https://github.com/GetDKAN/cmsds-open-data-components) +- [Drydock Cloud](https://github.com/drydockcloud) +- [Entity Field Fetch field](https://www.drupal.org/project/entity_field_fetch) +- [GovDelivery Bulletins](https://www.drupal.org/project/govdelivery_bulletins) +- [Mermaid Diagram Field](https://www.drupal.org/project/mermaid_diagram_field) +- [Node Link Report](https://www.drupal.org/project/node_link_report) +- [Open Accessibility Conformance Report](https://github.com/GSA/openacr) +- [Post API](https://www.drupal.org/project/post_api) +- [Vertex AI Search](https://www.drupal.org/project/vertex_ai_search) See more of [CivicActions Drupal contributions](https://drupal.org/civicactions). diff --git a/common-practices-tools/difficult-conversation.md b/common-practices-tools/difficult-conversation.md index 891dcaca0f..2911d75291 100644 --- a/common-practices-tools/difficult-conversation.md +++ b/common-practices-tools/difficult-conversation.md @@ -30,27 +30,27 @@ Finally, aim to reach a shared understanding and plan of action and wrap up the Use the following tips to help navigate the discussion: -- **Present your side with curiosity by:** - - Actively asking for the other team member's perspective. - - Listening intently. - - Providing feedback that indicates that you've heard what the other person has said. -- **Create and maintain a safe space by:** - - Apologizing when you are wrong, - - Repeating back what you've heard to confirm accuracy, - - Acknowledging when you have learned something new, and - - Stating your appreciation when they share. -- **Avoid sarcasm, judgment, comparisons, and blame by:** - - Recognizing your own emotions, and - - Sharing your perceptions of the emotions you are seeing from the team member. -- **Learn about them by:** - - Asking and learning about the team member's background and cultural differences. -- **Consider their perspective by:** - - Being aware that the team member may have experienced similar conversations in past workplaces that were upsetting or even traumatizing. -- **Brainstorm solutions together by:** - - Asking for ideas on how to improve or change the situation's impact. -- **Keep an open mind by:** - - Trying new ideas and trust that the team member will do the same. - - Committing to take the time needed to follow through. +- **Present your side with curiosity by:** + - Actively asking for the other team member's perspective. + - Listening intently. + - Providing feedback that indicates that you've heard what the other person has said. +- **Create and maintain a safe space by:** + - Apologizing when you are wrong, + - Repeating back what you've heard to confirm accuracy, + - Acknowledging when you have learned something new, and + - Stating your appreciation when they share. +- **Avoid sarcasm, judgment, comparisons, and blame by:** + - Recognizing your own emotions, and + - Sharing your perceptions of the emotions you are seeing from the team member. +- **Learn about them by:** + - Asking and learning about the team member's background and cultural differences. +- **Consider their perspective by:** + - Being aware that the team member may have experienced similar conversations in past workplaces that were upsetting or even traumatizing. +- **Brainstorm solutions together by:** + - Asking for ideas on how to improve or change the situation's impact. +- **Keep an open mind by:** + - Trying new ideas and trust that the team member will do the same. + - Committing to take the time needed to follow through. ## What's next @@ -58,9 +58,9 @@ Before ending the conversation, create a plan that outlines the next steps and s These conversations often require more than one discussion. It is important to check in later to ensure that concerns are being addressed or determine if the relationship needs more attention. -- Repeat the action items that will be addressed. -- Figure out a time when you can follow up on any action items. -- Review the action items with the person at a later date and acknowledge any progress. +- Repeat the action items that will be addressed. +- Figure out a time when you can follow up on any action items. +- Review the action items with the person at a later date and acknowledge any progress. ## Additional considerations @@ -72,7 +72,7 @@ For giving and receiving feedback review [conflict resolution and growth mindset ## Other readings & resources -- [Difficult conversation tools and skills](https://docs.google.com/document/d/1VXXqLRLNdjRFFKjBHEtt7CJyrUgnS5pR1fvM1a2F3Hc/edit?tab=t.0) discussion in 2022 virtual summit. -- Project team working agreements. -- Skills coach in Culture Amp. -- Training related to conversations and feedback. Ask PeopleOps about any options. +- [Difficult conversation tools and skills](https://docs.google.com/document/d/1VXXqLRLNdjRFFKjBHEtt7CJyrUgnS5pR1fvM1a2F3Hc/edit?tab=t.0) discussion in 2022 virtual summit. +- Project team working agreements. +- Skills coach in Culture Amp. +- Training related to conversations and feedback. Ask PeopleOps about any options. diff --git a/common-practices-tools/security/README.md b/common-practices-tools/security/README.md index 916fce29b4..7b9cf2c441 100644 --- a/common-practices-tools/security/README.md +++ b/common-practices-tools/security/README.md @@ -22,21 +22,21 @@ The password manager itself must be protected by a strong _memorized secret_ (th ### LastPass -- The [LastPass](https://www.lastpass.com/) password generator can create and maintain hundreds of different passwords. And LastPass has free iPhone and Android apps. - - We recommend a minimum of 16 character passwords using all character types. (Some old systems will need you to lessen this level of security, but those are few.) - - Once you have all your passwords in LastPass, take the "Security Challenge" - your score should be 80% or higher. -- LastPass is required for members of the CivicActions System Admins and DevSecOps Team. -- We recommend LastPass premium but do not require it. A premium account will enable unlimited sync across your devices and more robust two-factor authentication (e.g. with a [YubiKey](#yubikey) token). -- Set up Two Factor Authentication on your LastPass Account (see below). LastPass will be storing all your passwords, so make it secure. -- It is fine (and perhaps preferable, because your browser can only use one LastPass account at a time) to use a personal email address to create your LastPass account. +- The [LastPass](https://www.lastpass.com/) password generator can create and maintain hundreds of different passwords. And LastPass has free iPhone and Android apps. + - We recommend a minimum of 16 character passwords using all character types. (Some old systems will need you to lessen this level of security, but those are few.) + - Once you have all your passwords in LastPass, take the "Security Challenge" - your score should be 80% or higher. +- LastPass is required for members of the CivicActions System Admins and DevSecOps Team. +- We recommend LastPass premium but do not require it. A premium account will enable unlimited sync across your devices and more robust two-factor authentication (e.g. with a [YubiKey](#yubikey) token). +- Set up Two Factor Authentication on your LastPass Account (see below). LastPass will be storing all your passwords, so make it secure. +- It is fine (and perhaps preferable, because your browser can only use one LastPass account at a time) to use a personal email address to create your LastPass account. ### Disable browser password autofill LastPass provides secure password management especially when unlocked via Two Factor Authentication. Storing new passwords created in LastPass in your browser completely defeats this security, enabling anyone with access to your browser access to all your sites. If asked by your browser "Do you want to save this password in your browser?" answer "**No**". Then disable this insecure action altogether: -- In Chrome, go to chrome://settings/ and uncheck "Offer to save your web passwords" -- In Firefox, go to about:preferences#privacy and uncheck "Ask to save logins and passwords for websites" -- In Safari, go to Settings >> AutoFill and uncheck "User names and passwords" +- In Chrome, go to chrome://settings/ and uncheck "Offer to save your web passwords" +- In Firefox, go to about:preferences#privacy and uncheck "Ask to save logins and passwords for websites" +- In Safari, go to Settings >> AutoFill and uncheck "User names and passwords" ## Use Multi-Factor Authentication (MFA) @@ -54,14 +54,14 @@ Do not rely on SMS text messages for general two-factor authentication as it is #### LastPass Authenticator -- This provides tight integration with Lastpass, see: -- For installation see [iPhone](https://apps.apple.com/us/app/lastpass-authenticator/id1079110004) or [Android](https://play.google.com/store/apps/details?id=com.lastpass.authenticator&hl=en_US&gl=US) -- For more info, [see the support page](https://support.lastpass.com/s/document-item?language=en_US&bundleId=lastpass&topicId=LastPass/LastPass_Authenticator.html&_LANG=enus) +- This provides tight integration with Lastpass, see: +- For installation see [iPhone](https://apps.apple.com/us/app/lastpass-authenticator/id1079110004) or [Android](https://play.google.com/store/apps/details?id=com.lastpass.authenticator&hl=en_US&gl=US) +- For more info, [see the support page](https://support.lastpass.com/s/document-item?language=en_US&bundleId=lastpass&topicId=LastPass/LastPass_Authenticator.html&_LANG=enus) #### Authy -- For installation instructions (iPhone or Android), see: -- Guides for setting up Multi-Factor Authentication: +- For installation instructions (iPhone or Android), see: +- Guides for setting up Multi-Factor Authentication: #### YubiKey @@ -73,12 +73,12 @@ While YubiKey is the easiest to use on a daily basis, if you lose it you could g ### Partial list of MFA-Enabled services -- LastPass: [Multifactor Authentication Options](https://support.lastpass.com/s/document-item?language=en_US&bundleId=lastpass&topicId=LastPass%2Ft_lastpass_faqs_users_logging_in_using_diff_mfa_options.html&_LANG=enus) -- Google: [2 Step Verification](https://support.google.com/accounts/topic/28786?hl=en&ref_topic=3382253) -- GitHub (especially for your [CivicActions account](https://github.com/CivicActions)): [Securing your account with two-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa) -- GitLab: See [your profile](https://git.civicactions.net/profile/account) -- iCloud: [Two-factor authentication for Apple ID](https://support.apple.com/en-us/HT204915) -- Slack: [Enabling two-factor authentication](https://get.slack.help/hc/en-us/articles/204509068-Enabling-two-factor-authentication#enablingtwofactor-authentication) +- LastPass: [Multifactor Authentication Options](https://support.lastpass.com/s/document-item?language=en_US&bundleId=lastpass&topicId=LastPass%2Ft_lastpass_faqs_users_logging_in_using_diff_mfa_options.html&_LANG=enus) +- Google: [2 Step Verification](https://support.google.com/accounts/topic/28786?hl=en&ref_topic=3382253) +- GitHub (especially for your [CivicActions account](https://github.com/CivicActions)): [Securing your account with two-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa) +- GitLab: See [your profile](https://git.civicactions.net/profile/account) +- iCloud: [Two-factor authentication for Apple ID](https://support.apple.com/en-us/HT204915) +- Slack: [Enabling two-factor authentication](https://get.slack.help/hc/en-us/articles/204509068-Enabling-two-factor-authentication#enablingtwofactor-authentication) ### Multi-Factor redundancy and MFA backup codes @@ -86,39 +86,39 @@ As a final, crucially important step, **_you must have a backup second factor fo SMS can often be an easy backup, but it is known to be insecure. Most services that provide MFA provide multiple second factor options, and we recommend that you set up at least one of several backup strategies for each MFA-enabled service you use: -- Have a second YubiKey in safe keeping (the author of this article has three). -- [Authy](#authy) and [LastPass Authenticator](#lastpass-authenticator) provide ever-changing 6-digit codes and can securely backup to the cloud, so if you lose your phone you can pull your information back out of the cloud when setting up your new phone. _Hint: store your cloud backup password in LastPass (but make sure you have another mechanism to unlock LastPass!)_ -- Many services offer a downloadable set of single use "backup codes" that can be printed and kept in a safe place. _Hint: you can store backup codes from other services in LastPass in the Notes section._ +- Have a second YubiKey in safe keeping (the author of this article has three). +- [Authy](#authy) and [LastPass Authenticator](#lastpass-authenticator) provide ever-changing 6-digit codes and can securely backup to the cloud, so if you lose your phone you can pull your information back out of the cloud when setting up your new phone. _Hint: store your cloud backup password in LastPass (but make sure you have another mechanism to unlock LastPass!)_ +- Many services offer a downloadable set of single use "backup codes" that can be printed and kept in a safe place. _Hint: you can store backup codes from other services in LastPass in the Notes section._ ## Phishing and social engineering Social engineering is the most common attack vector used to compromise computer systems. Social engineering relies heavily on human interaction and often involves tricking people into breaking normal security procedures. The following is a brief reminder of some of the methods used, but is in no way complete. -- Phishing - - Is the email from someone you know and contains expected information? - - Emails from unknown people asking for some action on your part is the most common form of phishing. - - Don't click on links or open attachments: - - Unless you trust the sender and expect the link or attachment, - - Even if you trust the source (a From: address can be spoofed) hover first and check the URL - - If in doubt, ask an IT member (e.g. via Slack) or forward the email to an IT member - - [More on Phishing avoidance (from EFF)](https://ssd.eff.org/en/module/how-avoid-phishing-attacks) -- Windows Technical Support - - "Windows Technical Support has noticed that you have viruses or other malware on your computer..." -- Baiting - - Seemingly innocent (or interesting) abandoned USB, CD, DVD media with autorun -- Public Wi-Fi (e.g., coffee shop, airport, library) - - Turn off sharing - - Don't automatically connect to unknown Wi-Fi hotspots - - Confirm the network name - know the name of your hotspot! - - Watch out for an "Evil Twin" - a hotspot that looks good but could be an access point set up by an attacker (e.g., "StarbucksGuest" or "DeltaFreeWifi") - - Turn on your local firewall - - Use a VPN if possible - - CivicActions has an [internal company VPN](https://git.civicactions.net/devops/internal-it-wireguard-vpn/tree/master) that has a static exit IP that can be allow-listed to CivicActions' client services - - If you always use HTTPS and SSH for connectivity, you are essentially creating a trusted VPN tunnel with every connection. There could still be metadata collection and local DNS spoofing, but [public Wi-Fi is now reasonably safe](https://www.eff.org/deeplinks/2020/01/why-public-wi-fi-lot-safer-you-think) - - As usual, never enter your name or password information: - - when on an insecure (non-HTTPS or SSL encrypted) connection, or - - to a site that you have not verified is correct (by examining at the URL) - - [More on public Wi-Fi network safety (from FTC)](https://consumer.ftc.gov/articles/are-public-wi-fi-networks-safe-what-you-need-know) +- Phishing + - Is the email from someone you know and contains expected information? + - Emails from unknown people asking for some action on your part is the most common form of phishing. + - Don't click on links or open attachments: + - Unless you trust the sender and expect the link or attachment, + - Even if you trust the source (a From: address can be spoofed) hover first and check the URL + - If in doubt, ask an IT member (e.g. via Slack) or forward the email to an IT member + - [More on Phishing avoidance (from EFF)](https://ssd.eff.org/en/module/how-avoid-phishing-attacks) +- Windows Technical Support + - "Windows Technical Support has noticed that you have viruses or other malware on your computer..." +- Baiting + - Seemingly innocent (or interesting) abandoned USB, CD, DVD media with autorun +- Public Wi-Fi (e.g., coffee shop, airport, library) + - Turn off sharing + - Don't automatically connect to unknown Wi-Fi hotspots + - Confirm the network name - know the name of your hotspot! + - Watch out for an "Evil Twin" - a hotspot that looks good but could be an access point set up by an attacker (e.g., "StarbucksGuest" or "DeltaFreeWifi") + - Turn on your local firewall + - Use a VPN if possible + - CivicActions has an [internal company VPN](https://git.civicactions.net/devops/internal-it-wireguard-vpn/tree/master) that has a static exit IP that can be allow-listed to CivicActions' client services + - If you always use HTTPS and SSH for connectivity, you are essentially creating a trusted VPN tunnel with every connection. There could still be metadata collection and local DNS spoofing, but [public Wi-Fi is now reasonably safe](https://www.eff.org/deeplinks/2020/01/why-public-wi-fi-lot-safer-you-think) + - As usual, never enter your name or password information: + - when on an insecure (non-HTTPS or SSL encrypted) connection, or + - to a site that you have not verified is correct (by examining at the URL) + - [More on public Wi-Fi network safety (from FTC)](https://consumer.ftc.gov/articles/are-public-wi-fi-networks-safe-what-you-need-know) ## Keep your systems up-to-date @@ -136,7 +136,7 @@ If you haven't set up your hard drive with hardware encryption, there are softwa CivicActions strongly recommends full disk encryption (FDE) with FileVault, and requires it on Macs supplied by CivicActions for specific client work. -- [Use FileVault to encrypt the startup disk on your Mac](https://support.apple.com/en-us/HT204837) - setup instructions +- [Use FileVault to encrypt the startup disk on your Mac](https://support.apple.com/en-us/HT204837) - setup instructions Much more technical detail on securing your Mac: [macOS-Security-and-Privacy-Guide](https://github.com/drduh/macOS-Security-and-Privacy-Guide/blob/master/README.md). _This is useful but well beyond what is required by CivicActions._ @@ -152,9 +152,9 @@ Unlike Mac and Windows, you can only encrypt your drive during system installati With more work captured in the cloud by Slack, Gmail, Google Drive, GitHub, etc. there is less that needs to be backed up. But you won't know what you'll miss until your system doesn't boot up because of an unrecoverable hard drive (or SSD) error. At the least, back up your security keys and personal preferences directories, such as (examples in GNU/Linux): -- `~/.ssh/` -- `~/.gnupg/` -- `~/.config` +- `~/.ssh/` +- `~/.gnupg/` +- `~/.config` Consider committing your personalization files (like `~/.bashrc`) into a Git repository. Please ensure that you do _not_ commit any files that may contain private keys or passwords. @@ -171,22 +171,22 @@ When you delete a file, it doesn't actually go away. Usually, all that occurs is GNU/Linux: -- [How to delete file(s) in secure manner?](https://askubuntu.com/questions/57572/how-to-delete-files-in-secure-manner) (Ask Ubuntu) -- [How to: Delete your Data Securely on Linux](https://ssd.eff.org/en/module/how-delete-your-data-securely-linux) (from the EFF Surveillance Self-Defense guide) +- [How to delete file(s) in secure manner?](https://askubuntu.com/questions/57572/how-to-delete-files-in-secure-manner) (Ask Ubuntu) +- [How to: Delete your Data Securely on Linux](https://ssd.eff.org/en/module/how-delete-your-data-securely-linux) (from the EFF Surveillance Self-Defense guide) MacOS: -- [How to erase a disk for Mac](https://support.apple.com/en-us/HT208496) - if erasing your startup disk, use macOS Recovery -- [About macOS Recovery](https://support.apple.com/en-us/HT201314) - which will lead you to reinstallation: -- [How to reinstall macOS from macOS Recovery](https://support.apple.com/en-us/HT204904) +- [How to erase a disk for Mac](https://support.apple.com/en-us/HT208496) - if erasing your startup disk, use macOS Recovery +- [About macOS Recovery](https://support.apple.com/en-us/HT201314) - which will lead you to reinstallation: +- [How to reinstall macOS from macOS Recovery](https://support.apple.com/en-us/HT204904) More information and resources: -- [Guidelines for Media Sanitization](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-88r1.pdf) (pdf) (NIST SP 800-88, December 2014) -- [ATA Secure Erase](https://ata.wiki.kernel.org/index.php/ATA_Secure_Erase) +- [Guidelines for Media Sanitization](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-88r1.pdf) (pdf) (NIST SP 800-88, December 2014) +- [ATA Secure Erase](https://ata.wiki.kernel.org/index.php/ATA_Secure_Erase) ## Protecting your privacy CivicActions believes that your privacy is a right, and that private communications can be beneficial to business. Here's some tips on how FOSS can help: -- [Protecting Your Privacy with Encryption](encryption.md) +- [Protecting Your Privacy with Encryption](encryption.md) diff --git a/common-practices-tools/security/contingency-plan.md b/common-practices-tools/security/contingency-plan.md index 59a148bda5..e804492069 100644 --- a/common-practices-tools/security/contingency-plan.md +++ b/common-practices-tools/security/contingency-plan.md @@ -8,25 +8,25 @@ title: Contingency plan -- [Applicability](#applicability) -- [Overview](#overview) -- [Recovery objective](#recovery-objective) -- [Incident Response Team information](#incident-response-team-information) - - [Contact information](#contact-information) -- [Contingency plan outline](#contingency-plan-outline) - - [Activation and notification](#activation-and-notification) - - [Recovery](#recovery) - - [Reconstitution](#reconstitution) -- [External dependencies](#external-dependencies) - - [GitHub](#github) - - [GitLab](#gitlab) - - [StatusCake](#statuscake) - - [OpsGenie](#opsgenie) - - [JIRA](#jira) - - [Slack](#slack) - - [AWS](#aws) - - [Acquia Cloud Enterprise (ACE) Platform as a Service (PaaS)](#acquia-cloud-enterprise-ace-platform-as-a-service-paas) -- [How this document works](#how-this-document-works) +- [Applicability](#applicability) +- [Overview](#overview) +- [Recovery objective](#recovery-objective) +- [Incident Response Team information](#incident-response-team-information) + - [Contact information](#contact-information) +- [Contingency plan outline](#contingency-plan-outline) + - [Activation and notification](#activation-and-notification) + - [Recovery](#recovery) + - [Reconstitution](#reconstitution) +- [External dependencies](#external-dependencies) + - [GitHub](#github) + - [GitLab](#gitlab) + - [StatusCake](#statuscake) + - [OpsGenie](#opsgenie) + - [JIRA](#jira) + - [Slack](#slack) + - [AWS](#aws) + - [Acquia Cloud Enterprise (ACE) Platform as a Service (PaaS)](#acquia-cloud-enterprise-ace-platform-as-a-service-paas) +- [How this document works](#how-this-document-works) @@ -40,8 +40,8 @@ title: Contingency plan This Contingency Plan provides baseline guidance for the CivicActions Team when managing the disruption, compromise, or failure of any component of a CivicActions IRCP managed system, product or service ("system"). As a general guideline, we consider "disruption" to mean unexpected downtime or significantly reduced service lasting longer than: -- 30 minutes 0900 - 2100 Eastern Time Monday through Friday (standard U.S. business hours) -- 90 minutes at other times +- 30 minutes 0900 - 2100 Eastern Time Monday through Friday (standard U.S. business hours) +- 90 minutes at other times Scenarios where that could happen include unexpected downtime of key services, system data loss, or improper privilege escalation. In the case of a security incident, the team uses the [Security Incident Response Plan](incident-response-plan.md) as well. @@ -59,7 +59,7 @@ More than 3 hours of any system being offline during standard U.S. business hour Team contact information is available in the Google Drive: -- [CivicActions Incident Response Team contact sheet](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) with names and roles for CivicActions' Incident Response Team members. All CivicActions employees have access to this sheet. +- [CivicActions Incident Response Team contact sheet](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) with names and roles for CivicActions' Incident Response Team members. All CivicActions employees have access to this sheet. ## Contingency plan outline @@ -71,13 +71,13 @@ If the problem is identified as part of a [security incident response situation] The IC first notifies and coordinates with the people who are authorized to decide that the system is in a contingency plan situation: -- From CivicActions: - - Incident Commander - - Project Manager - - CivicActions Incident Response Team -- From the customer: - - Product Owner - - Users, when applicable +- From CivicActions: + - Incident Commander + - Project Manager + - CivicActions Incident Response Team +- From the customer: + - Product Owner + - Users, when applicable The IC keeps a log of the situation in the [`#general`](https://civicactions.slack.com/messages/general/) Slack channel or within a client-specific Slack channel, JIRA ticket, or GitHub issue. If this is also a security incident, the IC also follows the [security incident communications process](incident-response-plan.md#3-initiate-the-response). The IC should delegate assistant ICs for aspects of the situation as necessary. @@ -101,59 +101,59 @@ CivicActions managed systems often depend on several external services. In the e ### GitHub -- **Service:** -- **Status:** -- **Status:** +- **Service:** +- **Status:** +- **Status:** If GitHub becomes unavailable, systems will continue to operate in its current state. The disruption would only impact the team's ability to update code on the instances. ### GitLab -- **Service:** -- **Status:** +- **Service:** +- **Status:** If GitLab becomes unavailable, systems will continue to operate in their current state. The disruption would impact the team's ability to update code on the instances, which could have significant impact. ### StatusCake -- **Service:** -- **Status:** +- **Service:** +- **Status:** If there is a disruption in the StatusCake service, the Incident Response team will be notified by email. ### OpsGenie -- **Service:** -- **Status:** -- **Status:** +- **Service:** +- **Status:** +- **Status:** If there is a disruption in the OpsGenie service, all alerts automatically get delivered to the team via email. ### JIRA -- **Service:** -- **Status:** +- **Service:** +- **Status:** There is no direct impact to the platform if a disruption occurs. Primary incident communications will move to the [CivicActions `#general`](https://civicactions.slack.com/) Slack channel. ### Slack -- **Service:** -- **Status:** -- **Status:** +- **Service:** +- **Status:** +- **Status:** There is no direct impact to the platform if a disruption occurs. Primary incident communications will move to one of: -- IT Zoom: -- Google Meet: -- Google Chat: +- IT Zoom: +- Google Meet: +- Google Chat: ### AWS -- **Service:** -- **Status:** +- **Service:** +- **Status:** If needed, you can [manage and create new servers](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1). @@ -161,17 +161,17 @@ In case of a **significant** disruption, after receiving approval from our Autho ### Acquia Cloud Enterprise (ACE) Platform as a Service (PaaS) -- **Service:** -- **Status:** +- **Service:** +- **Status:** Some sites are hosted on the Acquia Cloud Enterprise (ACE) PaaS which is layered on top of the Amazon Web Services (AWS) FedRAMP-certified cloud in the us-east region. See [ACE Status](https://status.acquia.com/) and [AWS status](https://health.aws.amazon.com/health/status). -- **Acquia Security:** -- **Acquia Monitoring:** -- **Acquia Availability & Backups:** +- **Acquia Security:** +- **Acquia Monitoring:** +- **Acquia Availability & Backups:** Acquia Cloud takes hourly snapshots of EBS volumes that are saved to Amazon S3 providing geographically distributed data centers. @@ -184,8 +184,8 @@ system to a different region. This plan is most effective if all CivicActions team members know about it, remember that it exists, have the ongoing opportunity to give input based on their expertise, and keep it up to date. -- The CivicActions team is responsible for maintaining this document and updating it as needed. Any change to it must be approved and peer reviewed by at least another member of the team. - - All changes to the plan should be communicated to the rest of the team. - - At least once a year, and after major changes to our systems, we review and update the plan. -- How we protect this plan from unauthorized modification: - - This plan is stored in the CivicActions Guidebook GitHub repository () with authorization to modify it limited to the Incident Response Team by GitHub access controls. CivicActions policy is that changes are proposed by making a pull request and ask another team member to review and merge the pull request. +- The CivicActions team is responsible for maintaining this document and updating it as needed. Any change to it must be approved and peer reviewed by at least another member of the team. + - All changes to the plan should be communicated to the rest of the team. + - At least once a year, and after major changes to our systems, we review and update the plan. +- How we protect this plan from unauthorized modification: + - This plan is stored in the CivicActions Guidebook GitHub repository () with authorization to modify it limited to the Incident Response Team by GitHub access controls. CivicActions policy is that changes are proposed by making a pull request and ask another team member to review and merge the pull request. diff --git a/common-practices-tools/security/encryption.md b/common-practices-tools/security/encryption.md index 31b4c5c0b4..c037656116 100644 --- a/common-practices-tools/security/encryption.md +++ b/common-practices-tools/security/encryption.md @@ -31,8 +31,8 @@ Documents transferred within the CivicActions.com GSuite including Gmail and Gdr We recommend using both of these browser add-ons that enhance privacy without encryption: -- [Privacy Badger](https://www.eff.org/privacybadger) blocks most ads and cookie collectors. Open source and free. -- [uBlock Origin](https://ublockorigin.com) is an ad content blocker. Open source and free. +- [Privacy Badger](https://www.eff.org/privacybadger) blocks most ads and cookie collectors. Open source and free. +- [uBlock Origin](https://ublockorigin.com) is an ad content blocker. Open source and free. These services will have little to no impact on your browsing experience and can go a long way to minimizing the data others collect about you. @@ -46,10 +46,10 @@ We recommend [Signal.org](https://signal.org/), which is free (and open source). ## More resources -- [Protecting Your Privacy Online](https://duckduckgo.com/?q=protecting+your+privacy+online) (a DuckDuckGo search) -- [Privacy Friendly Search](https://info.ecosia.org/privacy) and more -- [5 Quick And Easy Ways To Encrypt Your Life Safely In Less Than An Hour](https://www.lifehack.org/562648/5-quick-and-easy-way-encrypt-your-life-safely) (includes [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en) and [DuckDuckGo](https://duckduckgo.com/)) -- [The ultimate guide to privacy on Android](https://www.computerworld.com/article/3545530/ultimate-guide-to-privacy-on-android.html) -- [16 Practical Privacy Tips for Your iPhone](https://www.nytimes.com/wirecutter/guides/iphone-privacy-tips/) -- [Tails - the amnesic incognito live system](https://tails.boum.org/) -- [Hardware that respects your freedom](https://ryf.fsf.org/) (Free Software Foundation) +- [Protecting Your Privacy Online](https://duckduckgo.com/?q=protecting+your+privacy+online) (a DuckDuckGo search) +- [Privacy Friendly Search](https://info.ecosia.org/privacy) and more +- [5 Quick And Easy Ways To Encrypt Your Life Safely In Less Than An Hour](https://www.lifehack.org/562648/5-quick-and-easy-way-encrypt-your-life-safely) (includes [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en) and [DuckDuckGo](https://duckduckgo.com/)) +- [The ultimate guide to privacy on Android](https://www.computerworld.com/article/3545530/ultimate-guide-to-privacy-on-android.html) +- [16 Practical Privacy Tips for Your iPhone](https://www.nytimes.com/wirecutter/guides/iphone-privacy-tips/) +- [Tails - the amnesic incognito live system](https://tails.boum.org/) +- [Hardware that respects your freedom](https://ryf.fsf.org/) (Free Software Foundation) diff --git a/common-practices-tools/security/gnupg.md b/common-practices-tools/security/gnupg.md index 2927e460b5..7cfcd622a8 100644 --- a/common-practices-tools/security/gnupg.md +++ b/common-practices-tools/security/gnupg.md @@ -14,10 +14,10 @@ title: Setting up GnuPG gpg --full-generate-key ``` -- Select "`(1) RSA and RSA (default)`" as the type. -- Select a 4096 bit keysize "`What keysize do you want? (3072) 4096`" -- Set the key to not expire "`Key is valid for? (0)`" -- Set your full name and the email address associated with your Github and Gitlab accounts: +- Select "`(1) RSA and RSA (default)`" as the type. +- Select a 4096 bit keysize "`What keysize do you want? (3072) 4096`" +- Set the key to not expire "`Key is valid for? (0)`" +- Set your full name and the email address associated with your Github and Gitlab accounts: ```shell Real name: first-name last-name @@ -27,7 +27,7 @@ You selected this USER-ID: "first-name last-name " ``` -- Set a complex passphrase for your private key. +- Set a complex passphrase for your private key. It should return: "`public and secret key created and signed.`" and the new keypair should be present under `.gnupg/` in your home directory. diff --git a/common-practices-tools/security/incident-response-checklist.md b/common-practices-tools/security/incident-response-checklist.md index 4f235d31b1..592a4d107f 100644 --- a/common-practices-tools/security/incident-response-checklist.md +++ b/common-practices-tools/security/incident-response-checklist.md @@ -22,18 +22,18 @@ A. Allocate 5 minutes and determine whether this event is a potential incident o B. Respond accordingly: -- Potential incident +- Potential incident 1. Issue a [broadcast notification](incident-response-plan.md#communication-channels) via one or more of the following: - - Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. - - Email to [security@civicactions.com](mailto:security@civicactions.com). - - Email/telephone to the [CivicActions IR Team](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) for an incident that has potential Project impact. + - Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. + - Email to [security@civicactions.com](mailto:security@civicactions.com). + - Email/telephone to the [CivicActions IR Team](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) for an incident that has potential Project impact. 2. For an incident requiring more than 30 minutes to resolve: - - Recruit additional IR Team responders via the Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@channel` to trigger a Slack notification for everyone in the channel. - - Designate an [**Incident Commander**](incident-response-plan.md#incident-commander) and [hand off the IC duties](incident-response-plan.md#explicit-handoff-ceremony). + - Recruit additional IR Team responders via the Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@channel` to trigger a Slack notification for everyone in the channel. + - Designate an [**Incident Commander**](incident-response-plan.md#incident-commander) and [hand off the IC duties](incident-response-plan.md#explicit-handoff-ceremony). More information on [incident response roles and responsibilities](incident-response-plan.md#roles-and-responsibilities): @@ -43,7 +43,7 @@ B. Respond accordingly: Use the [_Explicit Handoff Ceremony_](incident-response-plan.md#explicit-handoff-ceremony) when transferring/changing roles. -- False alarm +- False alarm Conclude the incident. Proceed to [_6. Conclude the incident_](#6-conclude-the-incident). @@ -68,34 +68,34 @@ _Reminder: Use the [Explicit Handoff Ceremony](incident-response-plan.md#explici ### Incident Commander assessment responsibilities -- Post an initial situation report, called a _sitrep_ ([example _sitrep_](incident-response-plan.md#4-assess-the-incident)), to the Slack channel [#general](https://civicactions.slack.com/messages/general/). Include a descriptive name, and identify the current Incident Commander and Responders. Use `@security` to trigger a Slack notification for the Security team. -- For an issue with potential Project impact, ensure that a JIRA ticket or Gitlab issue has been created. This should be done, even if the _First Responder/IC_ manages the incident fully, for example, by simply re-starting a service. +- Post an initial situation report, called a _sitrep_ ([example _sitrep_](incident-response-plan.md#4-assess-the-incident)), to the Slack channel [#general](https://civicactions.slack.com/messages/general/). Include a descriptive name, and identify the current Incident Commander and Responders. Use `@security` to trigger a Slack notification for the Security team. +- For an issue with potential Project impact, ensure that a JIRA ticket or Gitlab issue has been created. This should be done, even if the _First Responder/IC_ manages the incident fully, for example, by simply re-starting a service. ## 5. Remediate ### IR Team remediation responsibilities -- Determine the cause, implement a resolution, and return the system to normal operations. Make every attempt to identify the cause; this can prevent incident recurrence. +- Determine the cause, implement a resolution, and return the system to normal operations. Make every attempt to identify the cause; this can prevent incident recurrence. -- If suspicious activity is suspected or other unanswered questions exist, do the following before making any changes: +- If suspicious activity is suspected or other unanswered questions exist, do the following before making any changes: - - Make snapshots of relevant volumes and data. - - Preserve logs. - - Take screen captures of anomalous activity that can be used in post-remediation forensic analysis. - - Consider implementing a containment strategy. For example, reconfigure firewall rules for the affected instance to drop all ingress and egress traffic, except from specific IPs like yours, until forensics can be performed. + - Make snapshots of relevant volumes and data. + - Preserve logs. + - Take screen captures of anomalous activity that can be used in post-remediation forensic analysis. + - Consider implementing a containment strategy. For example, reconfigure firewall rules for the affected instance to drop all ingress and egress traffic, except from specific IPs like yours, until forensics can be performed. ### Incident Commander remediation responsibilities -- Maintain current information in Slack, shared Google Docs files, the ticket/issue (if applicable), or other [communication channels](incident-response-plan.md#communication-channels). Be sure to include: - - Project team leads and members - - Remediation items and their assignees -- Establish and document work shifts for an incident longer than 3 hours. -- Maintain communications with stakeholders, or designate a _Communications Officer_ via [explicit handoff](incident-response-plan.md#explicit-handoff-ceremony). -- Share _sitreps_ on a regular basis: - - High severity: hourly - - Medium severity: 2x daily - - Low severity: daily -- Focus on coordination, not remediation. +- Maintain current information in Slack, shared Google Docs files, the ticket/issue (if applicable), or other [communication channels](incident-response-plan.md#communication-channels). Be sure to include: + - Project team leads and members + - Remediation items and their assignees +- Establish and document work shifts for an incident longer than 3 hours. +- Maintain communications with stakeholders, or designate a _Communications Officer_ via [explicit handoff](incident-response-plan.md#explicit-handoff-ceremony). +- Share _sitreps_ on a regular basis: + - High severity: hourly + - Medium severity: 2x daily + - Low severity: daily +- Focus on coordination, not remediation. ## 6. Conclude the incident @@ -103,8 +103,8 @@ A. Notify the Slack channel [#general](https://civicactions.slack.com/messages/g B. Update the ticket/issue (if applicable) and set the status to one of the following: -- Confirmed incident: _Ready for QA_ -- False alarm: _Done_ +- Confirmed incident: _Ready for QA_ +- False alarm: _Done_ C. Schedule an [IR Team retrospective](incident-response-plan.md#conducting-a-retrospective). Optional for false alarms. diff --git a/common-practices-tools/security/incident-response-plan.md b/common-practices-tools/security/incident-response-plan.md index d8c4cc04b1..fbb53929ad 100644 --- a/common-practices-tools/security/incident-response-plan.md +++ b/common-practices-tools/security/incident-response-plan.md @@ -8,36 +8,36 @@ title: Incident response plan -- [Introduction](#introduction) -- [Roles and Responsibilities](#roles-and-responsibilities) - - [Responder](#responder) - - [First Responder](#first-responder) - - [IR Team Responders](#ir-team-responders) - - [Incident Commander](#incident-commander) - - [Communications Officer](#communications-officer) - - [Communication channels](#communication-channels) -- [Incident response process](#incident-response-process) - - [1. Breathe](#1-breathe) - - [2. Start documenting](#2-start-documenting) - - [3. Initiate the response](#3-initiate-the-response) - - [4. Assess the incident](#4-assess-the-incident) - - [IR Team responsibilities during assessment](#ir-team-responsibilities-during-assessment) - - [Incident Commander responsibilities during assessment](#incident-commander-responsibilities-during-assessment) - - [5. Remediate](#5-remediate) - - [Remediation and service disruption](#remediation-and-service-disruption) - - [Remediation requiring more than 3 hours](#remediation-requiring-more-than-3-hours) - - [IR Team responsibilities during remediation](#ir-team-responsibilities-during-remediation) - - [Incident Commander responsibilities during remediation](#incident-commander-responsibilities-during-remediation) - - [Communications during remediation](#communications-during-remediation) - - [6. Conclude the incident](#6-conclude-the-incident) - - [Closing the ticket](#closing-the-ticket) - - [Conducting a retrospective](#conducting-a-retrospective) - - [Developing the incident report](#developing-the-incident-report) -- [Incident severities](#incident-severities) - - [High severity](#high-severity) - - [Medium severity](#medium-severity) - - [Low severity](#low-severity) -- [Explicit Handoff Ceremony](#explicit-handoff-ceremony) +- [Introduction](#introduction) +- [Roles and Responsibilities](#roles-and-responsibilities) + - [Responder](#responder) + - [First Responder](#first-responder) + - [IR Team Responders](#ir-team-responders) + - [Incident Commander](#incident-commander) + - [Communications Officer](#communications-officer) + - [Communication channels](#communication-channels) +- [Incident response process](#incident-response-process) + - [1. Breathe](#1-breathe) + - [2. Start documenting](#2-start-documenting) + - [3. Initiate the response](#3-initiate-the-response) + - [4. Assess the incident](#4-assess-the-incident) + - [IR Team responsibilities during assessment](#ir-team-responsibilities-during-assessment) + - [Incident Commander responsibilities during assessment](#incident-commander-responsibilities-during-assessment) + - [5. Remediate](#5-remediate) + - [Remediation and service disruption](#remediation-and-service-disruption) + - [Remediation requiring more than 3 hours](#remediation-requiring-more-than-3-hours) + - [IR Team responsibilities during remediation](#ir-team-responsibilities-during-remediation) + - [Incident Commander responsibilities during remediation](#incident-commander-responsibilities-during-remediation) + - [Communications during remediation](#communications-during-remediation) + - [6. Conclude the incident](#6-conclude-the-incident) + - [Closing the ticket](#closing-the-ticket) + - [Conducting a retrospective](#conducting-a-retrospective) + - [Developing the incident report](#developing-the-incident-report) +- [Incident severities](#incident-severities) + - [High severity](#high-severity) + - [Medium severity](#medium-severity) + - [Low severity](#low-severity) +- [Explicit Handoff Ceremony](#explicit-handoff-ceremony) @@ -49,8 +49,8 @@ title: Incident response plan This document describes the process that the CivicActions Incident Response Team follows when responding to security incidents and other disruptions that may affect the Confidentiality, Integrity, Availability (CIA) or Privacy of system resources and data. It explains: -- roles and responsibilities during and after incidents -- overview of the steps to follow for resolution +- roles and responsibilities during and after incidents +- overview of the steps to follow for resolution _During an incident, the [IRP checklist](incident-response-checklist.md) may be more useful as it contains bulleted, actionable items for the IR Team to follow. For most non-project-related incidents, see the [Security Incidents](incidents.md) page._ @@ -66,17 +66,17 @@ A _Responder_ is a member of the CivicActions IR Team who investigates and remed The _First Responder_ is the first IR Team member who becomes aware of the incident. -- Frequently the _First Responder_ is also the _Incident Reporter_. -- The _First Responder_ assumes the role as the _Incident Commander_ (IC) until [handing off IC duties](#explicit-handoff-ceremony). -- For the first 15-30 minutes, the _First Responder_ may work alone. If needed, the _First Responder_ begins forming the IR Team. See [Initiate](#3-initiate-the-response). +- Frequently the _First Responder_ is also the _Incident Reporter_. +- The _First Responder_ assumes the role as the _Incident Commander_ (IC) until [handing off IC duties](#explicit-handoff-ceremony). +- For the first 15-30 minutes, the _First Responder_ may work alone. If needed, the _First Responder_ begins forming the IR Team. See [Initiate](#3-initiate-the-response). #### IR Team Responders During incident response, _Responders_ do the following: -- Assume primary responsibility for the [Assess](#4-assess-the-incident) and [Remediate](#5-remediate) steps. -- Document in real time the measurements, theories, and steps taken using the Slack channel [#general](https://civicactions.slack.com/messages/general/) or other channels provided by the _Incident Commander_ (IC). Use `@security` to trigger a Slack notification for the Security team. -- Designate an _Incident Commander_ (IC), if the incident might require more than 15-30 minutes to resolve, and do an [explicit handoff](#explicit-handoff-ceremony). +- Assume primary responsibility for the [Assess](#4-assess-the-incident) and [Remediate](#5-remediate) steps. +- Document in real time the measurements, theories, and steps taken using the Slack channel [#general](https://civicactions.slack.com/messages/general/) or other channels provided by the _Incident Commander_ (IC). Use `@security` to trigger a Slack notification for the Security team. +- Designate an _Incident Commander_ (IC), if the incident might require more than 15-30 minutes to resolve, and do an [explicit handoff](#explicit-handoff-ceremony). ### Incident Commander @@ -104,32 +104,32 @@ The _Incident Commander_ (IC) manages communications regarding the incident unti The _Communications Officer_ (CO) manages external communications with: -- Management, developers, users, and anyone affected by the incident -- Client stakeholders (if applicable) -- Additional Project team members and/or the Product Owner (if applicable) -- CivicActions Legal team, and US-CERT if escalation is required +- Management, developers, users, and anyone affected by the incident +- Client stakeholders (if applicable) +- Additional Project team members and/or the Product Owner (if applicable) +- CivicActions Legal team, and US-CERT if escalation is required #### Communication channels The _Incident Commander_ (IC) determines the most appropriate communication channels during incident response. Any of the following may be used: -- Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. -- During business hours, _Incident Commander_ (IC) may create a dedicated Slack channel (for example, #fire-team) for IR Team communications. -- A JIRA ticket or Github/Gitlab issue for the incident (if applicable) will be the final location for all incident reporting, with links to other documents as needed. -- Video conference: Zoom, Google Meet, Microsoft Teams, Skype, etc. (Be sure to record the call for documentation purposes.) -- Email to [security@civicactions.com](mailto:security@civicactions.com). -- Email/telephone to the [CivicActions IR Team](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) for an incident that has potential Project impact. +- Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. +- During business hours, _Incident Commander_ (IC) may create a dedicated Slack channel (for example, #fire-team) for IR Team communications. +- A JIRA ticket or Github/Gitlab issue for the incident (if applicable) will be the final location for all incident reporting, with links to other documents as needed. +- Video conference: Zoom, Google Meet, Microsoft Teams, Skype, etc. (Be sure to record the call for documentation purposes.) +- Email to [security@civicactions.com](mailto:security@civicactions.com). +- Email/telephone to the [CivicActions IR Team](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) for an incident that has potential Project impact. ## Incident response process There are six major processes of incident response, detailed below: -- [1. _Breathe_](#1-breathe) -- [2. Start documenting](#2-start-documenting) -- [3. Initiate the response](#3-initiate-the-response) -- [4. Assess the incident](#4-assess-the-incident) -- [5. Remediate](#5-remediate) -- [6. Conclude the incident](#6-conclude-the-incident) +- [1. _Breathe_](#1-breathe) +- [2. Start documenting](#2-start-documenting) +- [3. Initiate the response](#3-initiate-the-response) +- [4. Assess the incident](#4-assess-the-incident) +- [5. Remediate](#5-remediate) +- [6. Conclude the incident](#6-conclude-the-incident) _During an incident, the [IRP checklist](incident-response-checklist.md) may be more useful as it contains bulleted, actionable items for the IR Team to follow._ @@ -151,13 +151,13 @@ An incident begins when someone becomes aware of a disruption in expected normal B. Respond accordingly: -- Potential incident +- Potential incident 1. Issue a broadcast notification via one or more of the following: - - Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. - - Email to [security@civicactions.com](mailto:security@civicactions.com). - - Email/telephone to the [CivicActions IR Team](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) for an incident that has potential Project impact. + - Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. + - Email to [security@civicactions.com](mailto:security@civicactions.com). + - Email/telephone to the [CivicActions IR Team](https://drive.google.com/open?id=1P9TePYm2Gkly8EjxCzA2EmlTjUIBypE7-CbCZrRN1EA) for an incident that has potential Project impact. An example message follows. The format is not important, but the information fields are useful. @@ -176,8 +176,8 @@ B. Respond accordingly: 2. For an incident requiring more than 30 minutes to resolve: - - Recruit additional _Responders_ via the Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. - - Designate an [Incident Commander (IC)](#incident-commander) and [hand off the IC duties](#explicit-handoff-ceremony). + - Recruit additional _Responders_ via the Slack channel [#general](https://civicactions.slack.com/messages/general/). Use `@security` to trigger a Slack notification for the Security team. + - Designate an [Incident Commander (IC)](#incident-commander) and [hand off the IC duties](#explicit-handoff-ceremony). More information on [incident response roles and responsibilities](#roles-and-responsibilities): @@ -187,7 +187,7 @@ B. Respond accordingly: Use the [Explicit Handoff Ceremony](#explicit-handoff-ceremony) when transferring/changing roles. -- False alarm +- False alarm Conclude the incident. Proceed to [_6. Conclude the incident_](#6-conclude-the-incident). @@ -199,16 +199,16 @@ A. Confirm the incident. 1. Gather information, and document your findings. - - Was the event triggered by an [external dependency](contingency-plan.md#external-dependencies)? - - Is a system failure causing the disruption? + - Was the event triggered by an [external dependency](contingency-plan.md#external-dependencies)? + - Is a system failure causing the disruption? 2. Proceed to the next step for a confirmed incident. (For a false alarm, conclude the incident. Proceed to [_6. Conclude the incident_](#6-conclude-the-incident).) B. Assess the severity. -- Use the [rubric for determining severity](#incident-severities). Project incidents are generally "Low severity". -- Does it affect system or data Confidentiality, Integrity, Availability and/or Privacy? -- Note that severity can change over the lifespan of an incident, and it is acceptable for the IR Team to assess the initial severity quickly. +- Use the [rubric for determining severity](#incident-severities). Project incidents are generally "Low severity". +- Does it affect system or data Confidentiality, Integrity, Availability and/or Privacy? +- Note that severity can change over the lifespan of an incident, and it is acceptable for the IR Team to assess the initial severity quickly. C. Determine whether the IR Team needs to activate the [Contingency Plan](contingency-plan.md). Consider whether Disaster Recovery is required. @@ -218,11 +218,11 @@ _Reminder: Use the [Explicit Handoff Ceremony](#explicit-handoff-ceremony) when #### Incident Commander responsibilities during assessment -- Post an initial situation report (_sitrep_), in the following locations: +- Post an initial situation report (_sitrep_), in the following locations: - - Slack channel [#general](https://civicactions.slack.com/messages/general/) (Use `@security` to trigger a Slack notification for the Security team. Include link to the ticket/issue if applicable.) - - JIRA ticket or Gitlab issue (if applicable) - - Any other [communication channels](#communication-channels) as specified by the _Incident Commander_ (IC) (or _Communications Officer_ (CO)). + - Slack channel [#general](https://civicactions.slack.com/messages/general/) (Use `@security` to trigger a Slack notification for the Security team. Include link to the ticket/issue if applicable.) + - JIRA ticket or Gitlab issue (if applicable) + - Any other [communication channels](#communication-channels) as specified by the _Incident Commander_ (IC) (or _Communications Officer_ (CO)). Here is an example _sitrep_: @@ -232,7 +232,7 @@ _Reminder: Use the [Explicit Handoff Ceremony](#explicit-handoff-ceremony) when **Responders**: Spot the Dog, Farmer Dave **Description**: We've confirmed reports of escaped chickens. Looks like a fox may have tunneled into the run. Dave is working to fix the fence. Spot is tracking the fox. -- For an issue with potential Project impact, ensure that a ticket/issue has been created. This should be done, even if the _First Responder/IC_ manages the incident fully, for example, by simply re-starting a service. +- For an issue with potential Project impact, ensure that a ticket/issue has been created. This should be done, even if the _First Responder/IC_ manages the incident fully, for example, by simply re-starting a service. ### 5. Remediate @@ -242,29 +242,29 @@ Remediation is about resolving the issues caused by an incident. Remediation wil Remediation may require service disruption. If it does, the IR Team should proceed in a different way depending on the [severity](#incident-severities): -- **High severity**: Take action immediately, even if this causes disruption. Send a notification about the disruption as soon as possible. The CivicActions IR Team, or Project IR Team if applicable, does not need permission to take action at this level. -- **Medium severity**: Consult the other members of the CivicActions IR Team and agree on the best course of action. For an issue with Project impact, notify the Project leads about the planned action, and help them assess the relative risk of disruption versus security. If the leads are unavailable on Slack, contact them using the phone numbers in their Slack profiles. The Project team should reach a collaborative decision on action, with a bias towards disruption. If they cannot be reached within an hour, the Project IR Team may take action without them. -- **Low severity**: Consult the other members of the CivicActions IR Team and agree on the best course of action. For an issue with Project impact, notify the Project leads as described above. Do not take action until a mutually-agreed course of action has been determined. +- **High severity**: Take action immediately, even if this causes disruption. Send a notification about the disruption as soon as possible. The CivicActions IR Team, or Project IR Team if applicable, does not need permission to take action at this level. +- **Medium severity**: Consult the other members of the CivicActions IR Team and agree on the best course of action. For an issue with Project impact, notify the Project leads about the planned action, and help them assess the relative risk of disruption versus security. If the leads are unavailable on Slack, contact them using the phone numbers in their Slack profiles. The Project team should reach a collaborative decision on action, with a bias towards disruption. If they cannot be reached within an hour, the Project IR Team may take action without them. +- **Low severity**: Consult the other members of the CivicActions IR Team and agree on the best course of action. For an issue with Project impact, notify the Project leads as described above. Do not take action until a mutually-agreed course of action has been determined. #### Remediation requiring more than 3 hours Remediation takes time. If the issue progresses for more than 3 hours without being resolved, the _Incident Commander_ (IC) should plan for a long remediation. This means: -- The _Incident Commander_ (IC) determines whether remediation efforts will occur during business hours only or be continuous. This depends on the severity of the issue, and whether breaches are ongoing. -- For a continuous response, the _Incident Commander_ (IC) should plan shifts. This allows _Responders_ to take breaks and insures continuous coverage. Shifts should be no longer than 3 hours. Also, the _Incident Commander_ (IC) duties should rotate in shifts no longer than 3 hours. +- The _Incident Commander_ (IC) determines whether remediation efforts will occur during business hours only or be continuous. This depends on the severity of the issue, and whether breaches are ongoing. +- For a continuous response, the _Incident Commander_ (IC) should plan shifts. This allows _Responders_ to take breaks and insures continuous coverage. Shifts should be no longer than 3 hours. Also, the _Incident Commander_ (IC) duties should rotate in shifts no longer than 3 hours. #### IR Team responsibilities during remediation -- Determine the cause, implement a resolution, and return the system to normal operations. Make every attempt to identify the cause; this can prevent incident recurrence. -- Maintain a list of informational leads from the incident — actionable information about any security breaches, stolen data, etc. -- Develop a list of remediation steps. These can be tracked as checklists in Slack, shared Google Docs files, a JIRA ticket, Gitlab issue or another [communication channel](#communication-channels) as specified by the _Incident Commander_ (IC). +- Determine the cause, implement a resolution, and return the system to normal operations. Make every attempt to identify the cause; this can prevent incident recurrence. +- Maintain a list of informational leads from the incident — actionable information about any security breaches, stolen data, etc. +- Develop a list of remediation steps. These can be tracked as checklists in Slack, shared Google Docs files, a JIRA ticket, Gitlab issue or another [communication channel](#communication-channels) as specified by the _Incident Commander_ (IC). If suspicious activity is suspected or other unanswered questions exist, do the following before making any changes: -- Make snapshots of relevant volumes and data. -- Preserve logs. -- Take screen captures of anomalous activity that can be used in post-remediation forensic analysis. -- Consider implementing a containment strategy. For example, reconfigure firewall rules for the affected instance to drop all ingress and egress traffic, except from specific IPs like your own, until forensics can be performed. +- Make snapshots of relevant volumes and data. +- Preserve logs. +- Take screen captures of anomalous activity that can be used in post-remediation forensic analysis. +- Consider implementing a containment strategy. For example, reconfigure firewall rules for the affected instance to drop all ingress and egress traffic, except from specific IPs like your own, until forensics can be performed. #### Incident Commander responsibilities during remediation @@ -274,29 +274,29 @@ The _Incident Commander_ (IC) must distinguish between immediate concerns, which The _Incident Commander_ (IC) does do the following: -- Maintains current information in Slack, shared Google Docs files, a JIRA ticket, or another [communication channel](#communication-channels). Be sure to include: +- Maintains current information in Slack, shared Google Docs files, a JIRA ticket, or another [communication channel](#communication-channels). Be sure to include: - - IR Team members and their roles, and/or Project team leads and members (if applicable) - - Remediation items and their assignees + - IR Team members and their roles, and/or Project team leads and members (if applicable) + - Remediation items and their assignees -- Establishes and documents work shifts for an incident longer than 3 hours. -- Maintains communications with stakeholders, or designates a _Communications Officer_ (CO) via [explicit handoff](#explicit-handoff-ceremony). -- Shares _sitreps_ on a regular basis: +- Establishes and documents work shifts for an incident longer than 3 hours. +- Maintains communications with stakeholders, or designates a _Communications Officer_ (CO) via [explicit handoff](#explicit-handoff-ceremony). +- Shares _sitreps_ on a regular basis: - - High severity: hourly - - Medium severity: 2x daily - - Low severity: 1x daily + - High severity: hourly + - Medium severity: 2x daily + - Low severity: 1x daily -- Focuses on coordination, communication, and information collection -- not remediation. +- Focuses on coordination, communication, and information collection -- not remediation. #### Communications during remediation The _Incident Commander_ (IC) or _Communications Officer_ (CO) does this following: -- Coordinates with the CivicActions managers to apprise them of the situation. -- Coordinates with the Project Product Owner (PO), if applicable, to notify affected customers. -- Ensures that the IR Team is recording all actions in the appropriate designated [communication channels](#communication-channels). -- Shares _sitreps_ on a regular basis in Slack, in the ticket/issue (if applicable), and with stakeholders. See the section on [incident severities](#incident-severities) for suggested time intervals based on severity level. +- Coordinates with the CivicActions managers to apprise them of the situation. +- Coordinates with the Project Product Owner (PO), if applicable, to notify affected customers. +- Ensures that the IR Team is recording all actions in the appropriate designated [communication channels](#communication-channels). +- Shares _sitreps_ on a regular basis in Slack, in the ticket/issue (if applicable), and with stakeholders. See the section on [incident severities](#incident-severities) for suggested time intervals based on severity level. ### 6. Conclude the incident @@ -306,9 +306,9 @@ When the incident is no longer active, for example, the breach has been containe To conclude an incident, the _Incident Commander_ (IC) should: -- Set the status of the ticket/issue to **Ready for QA**. -- Send a final _sitrep_ to stakeholders, including CivicActions managers and the Security team. -- Thank everyone involved for their service. +- Set the status of the ticket/issue to **Ready for QA**. +- Send a final _sitrep_ to stakeholders, including CivicActions managers and the Security team. +- Thank everyone involved for their service. #### Conducting a retrospective @@ -318,16 +318,16 @@ An _Incident Commander_ (IC), or another designated party such as the _Communica The incident report should contain: -- a timeline of the incident -- details about how the incident progressed -- information about the vulnerabilities that led to the incident, also called a _cause analysis_ (The _cause analysis_ is an important part of the incident report. Tools such as [Infinite Hows](https://www.kitchensoap.com/2014/11/14/the-infinite-hows-or-the-dangers-of-the-five-whys/) and [Five Whys](https://en.wikipedia.org/wiki/5_Whys) can help the IR Team explore potential causes, prevention, and improved incident response.) +- a timeline of the incident +- details about how the incident progressed +- information about the vulnerabilities that led to the incident, also called a _cause analysis_ (The _cause analysis_ is an important part of the incident report. Tools such as [Infinite Hows](https://www.kitchensoap.com/2014/11/14/the-infinite-hows-or-the-dangers-of-the-five-whys/) and [Five Whys](https://en.wikipedia.org/wiki/5_Whys) can help the IR Team explore potential causes, prevention, and improved incident response.) Additionally, the incident report should include basic response metrics: -- **Discovery method**: How did the IR Team become aware of the issue? -- **Time to discovery**: How much time passed from the time the incident became active until someone became aware of it? -- **Time to containment**: How much time passed from the time someone became aware of the incident until the incident was contained? -- **Threat actions**: What actions were taken by the actor? For example, phishing, password attacks, etc. +- **Discovery method**: How did the IR Team become aware of the issue? +- **Time to discovery**: How much time passed from the time the incident became active until someone became aware of it? +- **Time to containment**: How much time passed from the time someone became aware of the incident until the incident was contained? +- **Threat actions**: What actions were taken by the actor? For example, phishing, password attacks, etc. The incident report should be posted in Slack, or in the ticket/issue as a final comment before the ticket is closed. @@ -339,49 +339,49 @@ The incident severity level determines the actions of the IR Team. Severity usua A high severity incident does one or more of the following: -- compromises the confidentiality/integrity of Sensitive Personally Identifiable Information (SPII), -- impacts the availability of services for a large number of customers, or -- has significant financial impact. +- compromises the confidentiality/integrity of Sensitive Personally Identifiable Information (SPII), +- impacts the availability of services for a large number of customers, or +- has significant financial impact. Examples include: -- Confirmed breach of SPII -- Successful root-level compromise of production systems -- Denial of Service attacks resulting in severe outages +- Confirmed breach of SPII +- Successful root-level compromise of production systems +- Denial of Service attacks resulting in severe outages Guidelines for incident response: -- Remediation efforts will likely be continuous until the issue is contained. -- _Responders_ may take any action required to contain the issue, including complete service degradation. -- _Sitreps_ should be shared every hour, or more frequently. +- Remediation efforts will likely be continuous until the issue is contained. +- _Responders_ may take any action required to contain the issue, including complete service degradation. +- _Sitreps_ should be shared every hour, or more frequently. ### Medium severity A medium severity incident can be an unsuccessful attempt to breach Personally Identifiable Information (PII), an event with limited impact on the availability of services for a large number of users, or an event with limited financial impact. Examples include: -- Suspected PII breach -- Targeted but unsuccessful attempts to compromise production systems -- Spam/phishing attacks targeting CivicActions or Project staff -- Denial of Service attacks resulting in limited service degradation +- Suspected PII breach +- Targeted but unsuccessful attempts to compromise production systems +- Spam/phishing attacks targeting CivicActions or Project staff +- Denial of Service attacks resulting in limited service degradation Guidelines for incident response: -- Response should occur during business hours. -- _Responders_ should attempt to consult stakeholders before causing downtime, but may proceed without consent if stakeholders do not respond in a reasonable time frame. -- _Sitreps_ should be shared approximately twice per day. +- Response should occur during business hours. +- _Responders_ should attempt to consult stakeholders before causing downtime, but may proceed without consent if stakeholders do not respond in a reasonable time frame. +- _Sitreps_ should be shared approximately twice per day. ### Low severity A low severity incident does not affect PII, and has no availability or financial impact. Examples include: -- Attempted compromise of non-important systems, for example, staging or testing instances -- Denial of Service attacks with no noticeable customer impact +- Attempted compromise of non-important systems, for example, staging or testing instances +- Denial of Service attacks with no noticeable customer impact Guidelines for incident response: -- Response should occur during business hours. -- _Responders_ should avoid service degradation unless stakeholders agree. -- _Sitreps_ should be shared daily. +- Response should occur during business hours. +- _Responders_ should avoid service degradation unless stakeholders agree. +- _Sitreps_ should be shared daily. ## Explicit Handoff Ceremony diff --git a/common-practices-tools/security/incidents.md b/common-practices-tools/security/incidents.md index ceea2a8c56..2711153dd8 100644 --- a/common-practices-tools/security/incidents.md +++ b/common-practices-tools/security/incidents.md @@ -8,9 +8,9 @@ Something went "bump" in the night (or the day)? This document explains what to Please remember: -- You are not in trouble when you report a security incident. -- When in doubt, report it. The security team decides if it's an actual incident. (For more information, see [What is an incident?](#what-is-an-incident)) -- We are all part of the Security team at CivicActions. +- You are not in trouble when you report a security incident. +- When in doubt, report it. The security team decides if it's an actual incident. (For more information, see [What is an incident?](#what-is-an-incident)) +- We are all part of the Security team at CivicActions. ## Handling phishing emails @@ -28,9 +28,9 @@ If you demonstrate a pattern of moderate to high risk behavior during these exer Everyone is expected to [report suspicious email messages using the Report phishing option in Gmail](https://support.google.com/mail/answer/8253?hl=en#zippy=%2Cuse-gmail-to-help-you-identify-phishing-emails%2Creport-a-phishing-email). When you report phishing threats in Gmail, Google responds automatically using a combination of the following actions: -- Displays a warning to other users about the message content -- Moves the suspicious message to the Spam folder -- Alerts Gmail administrators at CivicActions about unusual spikes in user reports +- Displays a warning to other users about the message content +- Moves the suspicious message to the Spam folder +- Alerts Gmail administrators at CivicActions about unusual spikes in user reports _Note: The Report phishing option is effective at thwarting phishing threats only in the Gmail web application ([mail.google.com](https://mail.google.com/))._ @@ -38,9 +38,9 @@ _Note: The Report phishing option is effective at thwarting phishing threats onl Please note that it is not considered a security risk to open an email, even if you do not know the sender or did not expect the message. [Many indicators of a suspcious email](https://support.google.com/mail/answer/8253?hl=en) can only be observed after you open the message. -- **If you got phished:** If you clicked a link, opened an attachment, or entered data into a form, [report it immediately as a security incident](#reporting-an-incident). Even if you don't think something bad happened, you must report it. Many incidents happen silently so you won't notice until the damage has been done. The security team can help you verify that your system is secure. +- **If you got phished:** If you clicked a link, opened an attachment, or entered data into a form, [report it immediately as a security incident](#reporting-an-incident). Even if you don't think something bad happened, you must report it. Many incidents happen silently so you won't notice until the damage has been done. The security team can help you verify that your system is secure. -- **If you received a suspicious email:** [Use the Report phishing option in Gmail](https://support.google.com/mail/answer/8253?hl=en#zippy=%2Cuse-gmail-to-help-you-identify-phishing-emails%2Creport-a-phishing-email). It is located in the options menu for the message. To access the menu, open or preview the message, expand the message options menu (look for the button with three dots), and select Report phishing. +- **If you received a suspicious email:** [Use the Report phishing option in Gmail](https://support.google.com/mail/answer/8253?hl=en#zippy=%2Cuse-gmail-to-help-you-identify-phishing-emails%2Creport-a-phishing-email). It is located in the options menu for the message. To access the menu, open or preview the message, expand the message options menu (look for the button with three dots), and select Report phishing. The Gmail web application is recommended. If you are using a mobile app or mail client, alert your CivicActions team members in the Slack channel [#loving-security](https://civicactions.slack.com/messages/loving-security/), or forward the message to [security@civicactions.com](mailto:security@civicactions.com). @@ -54,15 +54,15 @@ Report any potential incident as soon as possible. Time is critical so that the ### To report a security incident -- Send an email to [security@civicactions.com](mailto:security@civicactions.com) as soon as possible. If the incident is related to a phishing email, forward the email. -- Include _Security Incident_ in the subject line. -- Describe briefly what happened. -- Indicate the best way for the Security team to contact you, and include a telephone number as an alternate method if possible. +- Send an email to [security@civicactions.com](mailto:security@civicactions.com) as soon as possible. If the incident is related to a phishing email, forward the email. +- Include _Security Incident_ in the subject line. +- Describe briefly what happened. +- Indicate the best way for the Security team to contact you, and include a telephone number as an alternate method if possible. ### For a project-specific incident -- Report the incident in your project Slack channel, and mention `@security`. This alerts your project's Incident Response Team and the Project Manager (PM). -- Send an email to [security@civicactions.com](mailto:security@civicactions.com). This alerts the Security team so that we can be aware of this issue and any potential impact to CivicActions. +- Report the incident in your project Slack channel, and mention `@security`. This alerts your project's Incident Response Team and the Project Manager (PM). +- Send an email to [security@civicactions.com](mailto:security@civicactions.com). This alerts the Security team so that we can be aware of this issue and any potential impact to CivicActions. ### Honor the "do not delete" rule @@ -74,11 +74,11 @@ First, it's important to note: it's always OK to err on the side of reporting! T On to the answer to "what is an incident?": in a nutshell, an incident is anything that compromises (or could compromise) our or our client's "CIA": **Confidentiality, Integrity, or Availability.** -- **Confidentiality** means: "secrets". Personally identifiable information (PII) — names, addresses, phone numbers, social security numbers, etc. — is one very important class of secrets. So are your passwords, service credentials, internal non-public documents, many contractual and any copyrighted documents. Any time you suspect that any confidential information may have been leaked outside of CivicActions or a specific client who has rightful access to the information, you should open an incident. Note that this includes unknown users with elevated permissions on a site and access lists on Google docs. +- **Confidentiality** means: "secrets". Personally identifiable information (PII) — names, addresses, phone numbers, social security numbers, etc. — is one very important class of secrets. So are your passwords, service credentials, internal non-public documents, many contractual and any copyrighted documents. Any time you suspect that any confidential information may have been leaked outside of CivicActions or a specific client who has rightful access to the information, you should open an incident. Note that this includes unknown users with elevated permissions on a site and access lists on Google docs. -- **Integrity** means the soundness/fitness of purpose of our systems or information. So if a backup was lost, or a web page was altered, or if an app stopped logging for a while, or if some documents got deleted — those are integrity issues. Sometimes these can indicate deeper incidents (like an attacker deleting logs to cover their tracks), so it's important to report these, as well. +- **Integrity** means the soundness/fitness of purpose of our systems or information. So if a backup was lost, or a web page was altered, or if an app stopped logging for a while, or if some documents got deleted — those are integrity issues. Sometimes these can indicate deeper incidents (like an attacker deleting logs to cover their tracks), so it's important to report these, as well. -- **Availability** means the availability of the services we provide. So if an app goes down, dynamic pages fail to update, if something we expect to be running stops running or consistently runs slower than expected — those are availability issues. Note that this only refers to production systems (it's fine if your demo app crashes), and also only to unexpected downtime. If you shut something down temporarily for planned maintenance — go for it, not an incident. +- **Availability** means the availability of the services we provide. So if an app goes down, dynamic pages fail to update, if something we expect to be running stops running or consistently runs slower than expected — those are availability issues. Note that this only refers to production systems (it's fine if your demo app crashes), and also only to unexpected downtime. If you shut something down temporarily for planned maintenance — go for it, not an incident. Remember: it's totally OK — and encouraged — to fail towards the side of reporting something. Organizations with really healthy _Incident Response_ systems see a lot of false alarms, and a lot of very low severity reports. This is good, because it indicates that people feel comfortable reporting day-to-day issues. The more we do it, the better we'll get at it. And this is ultimately the goal, because then when something really serious happens, we'll be well-practiced at handling it smoothly and efficiently. diff --git a/common-practices-tools/security/securing-your-workspace.md b/common-practices-tools/security/securing-your-workspace.md index 6a9fb8bfe7..f3d44616d4 100644 --- a/common-practices-tools/security/securing-your-workspace.md +++ b/common-practices-tools/security/securing-your-workspace.md @@ -8,11 +8,11 @@ Notes on securing your workspace (linux, Mac or Windows) for various platforms a ## High Level Security Guidelines -- Screen lock -- Strong password -- Disk encryption -- Separate browser profile for work -- No smart devices that are always listening +- Screen lock +- Strong password +- Disk encryption +- Separate browser profile for work +- No smart devices that are always listening ### Mac diff --git a/common-practices-tools/security/yubikey.md b/common-practices-tools/security/yubikey.md index be4a9907c9..ceaab5608b 100644 --- a/common-practices-tools/security/yubikey.md +++ b/common-practices-tools/security/yubikey.md @@ -10,14 +10,14 @@ The YubiKey is a hardware device manufactured by Yubico that provides a hardware ### Operation -- Simply plug it into an unused USB port. -- During certain types of authentication you will be prompted on screen to press the inset copper button marked with and (often lit) "Y". +- Simply plug it into an unused USB port. +- During certain types of authentication you will be prompted on screen to press the inset copper button marked with and (often lit) "Y". ### Security Hints -- If you trust your environment (like at home) you can keep the YubiKey near or even plugged into your computer. -- In low trust environments (coffee shops, hotel rooms, etc.) keep your YubiKey with you at all times (in a pocket or purse), especially if step away from your computer, even briefly. If your computer is compromised, it won't be accessible without the YubiKey that you have on you. -- Do not use SMS text messages for multi-factor authentication. Your MFA is only as strong as the weakest method you have configured. +- If you trust your environment (like at home) you can keep the YubiKey near or even plugged into your computer. +- In low trust environments (coffee shops, hotel rooms, etc.) keep your YubiKey with you at all times (in a pocket or purse), especially if step away from your computer, even briefly. If your computer is compromised, it won't be accessible without the YubiKey that you have on you. +- Do not use SMS text messages for multi-factor authentication. Your MFA is only as strong as the weakest method you have configured. ## Enable YubiKey MFA for applications @@ -53,39 +53,39 @@ This requires a YubiKey token (cover the button for approximately one second) on For each Google account you have: -- Visit -- Enable TFA, and complete the phone verification process (phone will act as backup TFA). -- Click on "Security Keys" and follow instructions to add YubiKey. -- Return to the main page and add a second phone and/or print backup codes. -- As long as you have a backup, you can also install the YubiKey Authenticator app, and configure your account to use that for the backup TFA instead of SMS/phone - this is the same as the Google Authenticator app, except that it stores the credentials on your YubiKey instead of the phone. -- If you have funky devices/apps that don't support TFA, you can set an application specific password using that tab. This includes sending E-mail from your personal Gmail account using your civicactions.com IMAP, for instance. +- Visit +- Enable TFA, and complete the phone verification process (phone will act as backup TFA). +- Click on "Security Keys" and follow instructions to add YubiKey. +- Return to the main page and add a second phone and/or print backup codes. +- As long as you have a backup, you can also install the YubiKey Authenticator app, and configure your account to use that for the backup TFA instead of SMS/phone - this is the same as the Google Authenticator app, except that it stores the credentials on your YubiKey instead of the phone. +- If you have funky devices/apps that don't support TFA, you can set an application specific password using that tab. This includes sending E-mail from your personal Gmail account using your civicactions.com IMAP, for instance. ### GitHub -- Visit -- Enable TFA, and complete the phone verification process (phone will act as backup TFA). -- Then you can "Register new device" in the "Security keys" section +- Visit +- Enable TFA, and complete the phone verification process (phone will act as backup TFA). +- Then you can "Register new device" in the "Security keys" section ### AWS Root Account For each AWS account you have: -- Visit -- Under MFA, add a Virtual MFA device. -- Use YubiKey Authenticator app to scan the QR code, and enter the response code, then close and reopen the app and enter the second response code. +- Visit +- Under MFA, add a Virtual MFA device. +- Use YubiKey Authenticator app to scan the QR code, and enter the response code, then close and reopen the app and enter the second response code. ### AWS IAM Account Up to 8 different MFA devices can be assigned, with a combination of Yubikeys, hardware TOTP tokens and authenticator apps. -- Visit -- Choose your user name -- Select the "Security Credentials" tab -- Under Multi-factor Authentication(MFA), select "Assign MFA device" -- Enter a Device Name and Select "Security Key" -- Allow your browser access to your Yubikey, if prompted -- Enter your Yubikey's pin, if prompted -- Touch your Yubikey when instructed +- Visit +- Choose your user name +- Select the "Security Credentials" tab +- Under Multi-factor Authentication(MFA), select "Assign MFA device" +- Enter a Device Name and Select "Security Key" +- Allow your browser access to your Yubikey, if prompted +- Enter your Yubikey's pin, if prompted +- Touch your Yubikey when instructed ### Linux @@ -177,20 +177,20 @@ _Please help make this page more useful by adding links you found useful (descri _This should be straightforward, but waiting for a pull request that clearly explains how to:_ -- Enable `OTP`, `U2F` & `CCID` -- Personalize **Configuration Slot 2** with options: - - `chal-resp` (Set challenge-response mode) - - `chal-hmac` (Generate HMAC-SHA1 challenge responses) - - `hmac-lt64` (Calculate HMAC on less than 64 bytes input) - - `serial-api-visible` (Allow serial number to be read using an API call) +- Enable `OTP`, `U2F` & `CCID` +- Personalize **Configuration Slot 2** with options: + - `chal-resp` (Set challenge-response mode) + - `chal-hmac` (Generate HMAC-SHA1 challenge responses) + - `hmac-lt64` (Calculate HMAC on less than 64 bytes input) + - `serial-api-visible` (Allow serial number to be read using an API call) #### Install apps See: -- -- -- +- +- +- _tbd..._ diff --git a/common-practices-tools/skills-base.md b/common-practices-tools/skills-base.md index 39dca975e9..bac34b170d 100644 --- a/common-practices-tools/skills-base.md +++ b/common-practices-tools/skills-base.md @@ -6,12 +6,12 @@ title: Skills Base Skills Base is a tool that lets us catalog our skills across the team and track who has what skills, interests, and qualifications. This is useful in many ways: -- So individuals can make plans around where they want to grow -- So individuals can figure out who to ask if they have a question -- So practice areas can identify who knows what, as well as identify opportunities to grow as a team -- To support people planning -- To support the sales process -- To support hiring +- So individuals can make plans around where they want to grow +- So individuals can figure out who to ask if they have a question +- So practice areas can identify who knows what, as well as identify opportunities to grow as a team +- To support people planning +- To support the sales process +- To support hiring Time spent on Skills Base can be tracked to PRODEV_COMMPART -> Professional Development. @@ -31,10 +31,10 @@ When you first log in you will need to go through a short onboarding: Notes: -- If you have specific additional skills you can add these (after the initial self-assessment) by navigating to [your skills tab](https://app.skills-base.com/people/view#skills) and clicking "Add a skill". -- If you normally work in more than one of the teams listed then open a [support ticket](software-and-support/README.md#to-request-support) to request those be added to your user. -- If you work in an internal department, select the "CivicActions" team. -- Skills Base does support supervisor assessments, but we are not currently using that functionality. +- If you have specific additional skills you can add these (after the initial self-assessment) by navigating to [your skills tab](https://app.skills-base.com/people/view#skills) and clicking "Add a skill". +- If you normally work in more than one of the teams listed then open a [support ticket](software-and-support/README.md#to-request-support) to request those be added to your user. +- If you work in an internal department, select the "CivicActions" team. +- Skills Base does support supervisor assessments, but we are not currently using that functionality. Next, you will need to take an initial self-assessment. This typically takes around 30 minutes, depending on the number of skills your team tracks. @@ -44,14 +44,14 @@ In general, you will be following the instructions on screen and clicking the bu We do include some hints as well as specifics here though, so please read this first: -- For each skill, you will be choosing a skill level on a 1-5 scale and an (optional) interest level. -- Before you start, _hover over each skill and interest level_ (on the right) to read the definitions of each. -- Many skills include more detail. _Hover over the skill name_ to read these to ensure you understand the scope of this skill. If it's still not clear, then use your best judgement (we will add more detail over time). -- Be honest: there are huge range of skills listed and even highly senior team members are likely to have a bunch of 1s and 2s. Being able to identify weaknesses makes it possible to grow. -- The interest level is optional. It's fine to leave most skills as "not applicable" if you don't have anything specific to communicate. -- Feel free to note any "Ah-has" in the comments, as well as any skills that you have that are in this category but weren't listed. -- You can use the arrow keys and tab to rate with a keyboard. -- There is a progress bar at the top. Depending on your team, you might have a few pages to go though, so feel free to stop and come back later if needed. +- For each skill, you will be choosing a skill level on a 1-5 scale and an (optional) interest level. +- Before you start, _hover over each skill and interest level_ (on the right) to read the definitions of each. +- Many skills include more detail. _Hover over the skill name_ to read these to ensure you understand the scope of this skill. If it's still not clear, then use your best judgement (we will add more detail over time). +- Be honest: there are huge range of skills listed and even highly senior team members are likely to have a bunch of 1s and 2s. Being able to identify weaknesses makes it possible to grow. +- The interest level is optional. It's fine to leave most skills as "not applicable" if you don't have anything specific to communicate. +- Feel free to note any "Ah-has" in the comments, as well as any skills that you have that are in this category but weren't listed. +- You can use the arrow keys and tab to rate with a keyboard. +- There is a progress bar at the top. Depending on your team, you might have a few pages to go though, so feel free to stop and come back later if needed. When you are done with your self-assessment, please click on "Review my Qualifications" and add or update your qualifications. @@ -61,54 +61,54 @@ Accurate tracking of our team qualifications is important to meet our contract r There are a few types of qualifications we need to track, some of which are not what people typically think of as qualifications. Please go through and check each category: -- **Academic qualifications** - prefixed with "Degree:" -- **Professional qualifications/certificates** - these are prefixed by the name of the issuing organization -- **US Federal background check form submissions** - these are prefixed with "US Background Check Form". If you aren't sure which form you submitted, check your e-mails or ask your project manager. -- **US Federal background check adjudications** - these are prefixed with "US Background Check Adjudication:" and the name of the agency that made that adjudication. If you aren't sure if you have received and adjudication, ask your project manager. In many cases we may need to estimate the date. -- **Agency-level project trainings (security, privacy etc)** - these are prefixed with the country and name of the agency that manages the training (occasionally trainings taken for one agency may be issued by another agency). If you aren't sure which you have taken, you may want to refer to your project onboarding, training system or other tracking ticket/sheet. +- **Academic qualifications** - prefixed with "Degree:" +- **Professional qualifications/certificates** - these are prefixed by the name of the issuing organization +- **US Federal background check form submissions** - these are prefixed with "US Background Check Form". If you aren't sure which form you submitted, check your e-mails or ask your project manager. +- **US Federal background check adjudications** - these are prefixed with "US Background Check Adjudication:" and the name of the agency that made that adjudication. If you aren't sure if you have received and adjudication, ask your project manager. In many cases we may need to estimate the date. +- **Agency-level project trainings (security, privacy etc)** - these are prefixed with the country and name of the agency that manages the training (occasionally trainings taken for one agency may be issued by another agency). If you aren't sure which you have taken, you may want to refer to your project onboarding, training system or other tracking ticket/sheet. You can access the qualifications section by going to "My summary" in the sidebar, then selecting the "Qualifications" tab. For each qualification: -- Enter the status and start and end dates (if applicable). -- If you already have qualifications listed, take a moment to review each one as well as adding any new ones. +- Enter the status and start and end dates (if applicable). +- If you already have qualifications listed, take a moment to review each one as well as adding any new ones. ## Updating your skills and qualifications -- Add or update qualifications whenever you get new ones (keeping in mind the categories above) or let one lapse. -- Team members will get an e-mail reminder to update their self assessment annually. Please keep them up to date! -- You can update your qualificiations more frequently though, if you want to track progress towards your goals. +- Add or update qualifications whenever you get new ones (keeping in mind the categories above) or let one lapse. +- Team members will get an e-mail reminder to update their self assessment annually. Please keep them up to date! +- You can update your qualificiations more frequently though, if you want to track progress towards your goals. ## Using Skills Base information ### For individuals -- Open "My summary" or navigate to a team member via the "People" menu. -- You can see qualifications, top skill cantegories, and individual skills, top interests, and people with similar skills. -- You can also see "Keen to improve" which lists skills with low skill but high interest. -- Use the tabs to dig deeper, as well as to look at changes in skills over time. +- Open "My summary" or navigate to a team member via the "People" menu. +- You can see qualifications, top skill cantegories, and individual skills, top interests, and people with similar skills. +- You can also see "Keen to improve" which lists skills with low skill but high interest. +- Use the tabs to dig deeper, as well as to look at changes in skills over time. ### By skill category or skill -- Navigate to the skill category or specific skill of interest using the search function or using the Skills directory and drilling down. - - In the directory, right-click on the skill category or skill and select "View" to open the page. -- On this page you can see who is most skilled, most interested, and most keen to improve (see above). -- On skill category pages, you can also see the skills within the category that have the highest skill and interest levels. +- Navigate to the skill category or specific skill of interest using the search function or using the Skills directory and drilling down. + - In the directory, right-click on the skill category or skill and select "View" to open the page. +- On this page you can see who is most skilled, most interested, and most keen to improve (see above). +- On skill category pages, you can also see the skills within the category that have the highest skill and interest levels. ## For teams -- Navigate to the team of interest by clicking "My team", using the search function or using the Teams directory and drilling down (right click and select "View"). -- On this page you can see who is most skilled, most interested, which skills associated with the team that have the highest skill, and interest levels. -- You can also see the top qualifications for this team and which self assessments are due. +- Navigate to the team of interest by clicking "My team", using the search function or using the Teams directory and drilling down (right click and select "View"). +- On this page you can see who is most skilled, most interested, which skills associated with the team that have the highest skill, and interest levels. +- You can also see the top qualifications for this team and which self assessments are due. ### Setting team targets This enables a team to set targets for each skill. Team members can then see how their own skill levels compare to this target and which skills they may want to focus on. -- From the team page, open the "Targets" tab. -- Click the "Set targets now" button. -- Follow the prompts. +- From the team page, open the "Targets" tab. +- Click the "Set targets now" button. +- Follow the prompts. It is recommended to use a collaborative process to set targets that includes other members of the team. It is not necessary to set a target for every skill or competency, the team can limit it to only skills they feel are important for everyone to hold. @@ -116,9 +116,9 @@ It is recommended to use a collaborative process to set targets that includes ot You can access team reports via the "Reports" dropdown: -- Heat matrix (by skill or interest levels) is a great way of looking at the strengths an opportunities/gaps for the team as a whole. -- Capability matrix shows how many people in the team have reported a specific skill level. -- You can also export data to analyse using external tools. +- Heat matrix (by skill or interest levels) is a great way of looking at the strengths an opportunities/gaps for the team as a whole. +- Capability matrix shows how many people in the team have reported a specific skill level. +- You can also export data to analyse using external tools. ## Finding people with a particular set of skills @@ -140,7 +140,7 @@ Note that the categories of skills [do not correspond 1-1 with teams](https://su In some cases, there may be some cross-over or duplication of skills between two teams. In this case, both teams will need to work together to identify how to refactor the catalog to ensure it is logical and avoids duplicate skills or overlap. The IT department can help facilitate these changes as needed. -- Open a [support ticket](software-and-support/README.md#to-request-support) to request access to manage skills. -- Request training from IT if you haven't done this before. -- Spend time becoming familiar with the catalog as a whole and search for similar skills before adding new ones. -- Add descriptions to each skill wherever possible. +- Open a [support ticket](software-and-support/README.md#to-request-support) to request access to manage skills. +- Request training from IT if you haven't done this before. +- Spend time becoming familiar with the catalog as a whole and search for similar skills before adding new ones. +- Add descriptions to each skill wherever possible. diff --git a/common-practices-tools/software-and-support/README.md b/common-practices-tools/software-and-support/README.md index bb4625258f..3537aed2ab 100644 --- a/common-practices-tools/software-and-support/README.md +++ b/common-practices-tools/software-and-support/README.md @@ -8,14 +8,14 @@ Note: this is the process for requesting internal support. We also have a [help ## To request support -- Identify the appropriate channel for your support request. This is often a practice area, department or project channel. - - Using the right channel is helpful for visibility as well as to enable other people to follow or participate. -- Invite the "@Assist" bot user to this channel (`/invite @Assist`) if they are not already a member (this user is already on most channels, this step is rarely needed). -- Write your request - it's helpful to include context as well as make your outcome/goal clear. -- Emoji react with `:ticket:` to your message. - - If there is prior discussion that includes helpful context you can include those in your request by emoji reacting with `:pushpin:` to each message before creating the ticket. - - Alternatively you can click "..." ("More actions") on the message and select "Create a ticket with Atlassian Assist". - - If you are having trouble creating a ticket ping the internal support team directly using the @it-help handle on any public channel. +- Identify the appropriate channel for your support request. This is often a practice area, department or project channel. + - Using the right channel is helpful for visibility as well as to enable other people to follow or participate. +- Invite the "@Assist" bot user to this channel (`/invite @Assist`) if they are not already a member (this user is already on most channels, this step is rarely needed). +- Write your request - it's helpful to include context as well as make your outcome/goal clear. +- Emoji react with `:ticket:` to your message. + - If there is prior discussion that includes helpful context you can include those in your request by emoji reacting with `:pushpin:` to each message before creating the ticket. + - Alternatively you can click "..." ("More actions") on the message and select "Create a ticket with Atlassian Assist". + - If you are having trouble creating a ticket ping the internal support team directly using the @it-help handle on any public channel. The support bot @Assist will notice this and create a thread/ticket to track the request. Someone from the support team will respond in the thread. @@ -25,5 +25,5 @@ Once the request is complete please close the ticket using the button in the thr This team is responsible for supporting: -- Internal systems and services (Slack, Zoom, GSuite, Gitlab, CI server etc) -- Project sandbox/CI escalations (i.e. a team/person is blocked and the project team has been unable to resolve) +- Internal systems and services (Slack, Zoom, GSuite, Gitlab, CI server etc) +- Project sandbox/CI escalations (i.e. a team/person is blocked and the project team has been unable to resolve) diff --git a/common-practices-tools/software-and-support/email.md b/common-practices-tools/software-and-support/email.md index c26f844138..bd2f245d73 100644 --- a/common-practices-tools/software-and-support/email.md +++ b/common-practices-tools/software-and-support/email.md @@ -6,23 +6,23 @@ title: Email ## Internal lists -- We use occasionally for team wide communication, and important announcements (Slack #announcements used more often, however) -- We use for HR notices, etc. (it is generally low traffic) -- Other email lists: ca-\[functionalgroup] -sales, -dev, -team, etc. -- Every project has its own list as a way to overhear each other +- We use occasionally for team wide communication, and important announcements (Slack #announcements used more often, however) +- We use for HR notices, etc. (it is generally low traffic) +- Other email lists: ca-\[functionalgroup] -sales, -dev, -team, etc. +- Every project has its own list as a way to overhear each other ## Client and staff lists -- (includes clients) -- (just for CivicActions staff) +- (includes clients) +- (just for CivicActions staff) ## Protocol We default to using our mailing lists for transparency instead of direct email messages. To get someone's attention, put their name in all caps in subject. Or use "ALL" to get everyone's attention. For example: -- Subject: "ELIZABETH: are you around this afternoon?" -- Subject: "ALL: please update your hours by EOD" -- Subject: "URGENT: please update your hours by EOD" +- Subject: "ELIZABETH: are you around this afternoon?" +- Subject: "ALL: please update your hours by EOD" +- Subject: "URGENT: please update your hours by EOD" ## Email Filters diff --git a/common-practices-tools/software-and-support/github.md b/common-practices-tools/software-and-support/github.md index 394e43b17b..064237603f 100644 --- a/common-practices-tools/software-and-support/github.md +++ b/common-practices-tools/software-and-support/github.md @@ -15,8 +15,8 @@ There are times where data or code needs to be kept private. In most instances w Many CivicActions employees will already have a GitHub account. If you don't have one yet, now's a great time to create one! Follow these steps: 1. Sign up with a free profile on . - - Use a personal email account, not your CivicActions one, so that your GitHub account will be portable. - - As always, please use a unique, secure password. + - Use a personal email account, not your CivicActions one, so that your GitHub account will be portable. + - As always, please use a unique, secure password. 2. Ask a coworker to add you to the [CivicActions team](https://github.com/orgs/CivicActions/teams/civicactions-team) and any relevant [subteams](https://github.com/orgs/CivicActions/teams/civicactions-team/teams). 3. Find out the details of the repositories you'll be working with. 4. Good work! Now [set up two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa). diff --git a/common-practices-tools/software-and-support/google-calendar.md b/common-practices-tools/software-and-support/google-calendar.md index 2d50b63f02..8c7ef0e5c4 100644 --- a/common-practices-tools/software-and-support/google-calendar.md +++ b/common-practices-tools/software-and-support/google-calendar.md @@ -18,17 +18,17 @@ title: Google Calendar ## Best Practices -- Set your location, time zone and working hours (& keep them current) using calendar settings: ![Calendar Settings](../../assets/images/CivicActions_Calendar_Settings.png "Calendar settings") -- Always send invitations to -- Make sure your main calendar is at sharing at least free/busy with everyone in CivicActions -- Consider enabling "speedy meetings" in Settings to encourage meetings to wrap up early for breaks in between -- Reply to meeting invitations (yes, no, maybe) -- Use the "optional" feature for attendees who are not required to attend (or don't invite them at all!) -- Use the Find a Time feature to identify a meeting time where all required participants are free. !["Find a Time"](../../assets/images/CivicActions_Calendar_FindTime.png "Find a time") -- Complete the Event Details section and add an agenda when creating an event -- If your event is related to a ticket, then include the ticket reference in the event title (e.g. a Jira RD-19 ticket event could be "Prototype Meeting RD-19") -- Create your Zoom meeting link in the event (ask a UXer or PM if you need to borrow a link for a meeting over 40 minutes) -- You can block off "heads down" time during your days for focus on your project work -- Block of your calendar for personal events where you don't want to get booked by anyone (dr appt, long lunch, pick up the kids, etc) -- Consider showing two timezones on your calendar view to make timezone conversions a breeze (feature in settings) -- When you email the ca-schedule listserv, your OOO time will be added the Out of Office Calendar !["CivicActions: Out of Office"](../../assets/images/ooo-cal1.png "Out of Office Calendar") +- Set your location, time zone and working hours (& keep them current) using calendar settings: ![Calendar Settings](../../assets/images/CivicActions_Calendar_Settings.png "Calendar settings") +- Always send invitations to +- Make sure your main calendar is at sharing at least free/busy with everyone in CivicActions +- Consider enabling "speedy meetings" in Settings to encourage meetings to wrap up early for breaks in between +- Reply to meeting invitations (yes, no, maybe) +- Use the "optional" feature for attendees who are not required to attend (or don't invite them at all!) +- Use the Find a Time feature to identify a meeting time where all required participants are free. !["Find a Time"](../../assets/images/CivicActions_Calendar_FindTime.png "Find a time") +- Complete the Event Details section and add an agenda when creating an event +- If your event is related to a ticket, then include the ticket reference in the event title (e.g. a Jira RD-19 ticket event could be "Prototype Meeting RD-19") +- Create your Zoom meeting link in the event (ask a UXer or PM if you need to borrow a link for a meeting over 40 minutes) +- You can block off "heads down" time during your days for focus on your project work +- Block of your calendar for personal events where you don't want to get booked by anyone (dr appt, long lunch, pick up the kids, etc) +- Consider showing two timezones on your calendar view to make timezone conversions a breeze (feature in settings) +- When you email the ca-schedule listserv, your OOO time will be added the Out of Office Calendar !["CivicActions: Out of Office"](../../assets/images/ooo-cal1.png "Out of Office Calendar") diff --git a/common-practices-tools/software-and-support/google-docs.md b/common-practices-tools/software-and-support/google-docs.md index c589bb8e6e..3e600edb83 100644 --- a/common-practices-tools/software-and-support/google-docs.md +++ b/common-practices-tools/software-and-support/google-docs.md @@ -4,13 +4,13 @@ title: Google Docs # Google Docs -- Google Docs allows you to create and share a variety of documents such as text documents, spreadsheets, presentations, and forms. -- Google Docs should be shared with your CivicActions email account -- If a link is shared with you, you can add yourself to the share list so you can reference it later on -- If you are using a template, always make a COPY -- Update [default paragraph styles](https://docs.google.com/document/d/1M-q4Wh0TfKctkaHRmJQumsIn_faTimyTub8qu3qGM7k/edit) to match CivicActions standard styles when creating new docs to use/share -- When you create a document, set permissions so "anyone at CivicActions can find and access" -- Make sure to place documents & files in appropriate project folder instead of it living at your personal My Drive +- Google Docs allows you to create and share a variety of documents such as text documents, spreadsheets, presentations, and forms. +- Google Docs should be shared with your CivicActions email account +- If a link is shared with you, you can add yourself to the share list so you can reference it later on +- If you are using a template, always make a COPY +- Update [default paragraph styles](https://docs.google.com/document/d/1M-q4Wh0TfKctkaHRmJQumsIn_faTimyTub8qu3qGM7k/edit) to match CivicActions standard styles when creating new docs to use/share +- When you create a document, set permissions so "anyone at CivicActions can find and access" +- Make sure to place documents & files in appropriate project folder instead of it living at your personal My Drive ![Open settings](../../assets/images/sharing1.png "Open settings") ![Advanced settings](../../assets/images/sharing2.png "Advanced settings") diff --git a/common-practices-tools/software-and-support/google-meet.md b/common-practices-tools/software-and-support/google-meet.md index 5f2b2a1c95..7aad63cf8c 100644 --- a/common-practices-tools/software-and-support/google-meet.md +++ b/common-practices-tools/software-and-support/google-meet.md @@ -8,19 +8,19 @@ title: Google Meet While Zoom is our default video meeting service, there are a few use cases for using Google Meet. -- If your Zoom meeting is being used by another team member when you want to video meet with someone else, you can create a Google Meet call -- Some clients can access Google products but cannot use Zoom, so your team may default to Google Meet in those cases -- There is no time limit length for Google Meet calls (wheres as Zoom has limits for the basic users) -- With both Google Meet and Zoom, you can share the meeting info (link and dial in info), but with Google Meet you can dial someone into the call yourself -- In Zoom, only the meeting host (or co-hosts) can mute others, but in Google Meet anyone can mute anyone +- If your Zoom meeting is being used by another team member when you want to video meet with someone else, you can create a Google Meet call +- Some clients can access Google products but cannot use Zoom, so your team may default to Google Meet in those cases +- There is no time limit length for Google Meet calls (wheres as Zoom has limits for the basic users) +- With both Google Meet and Zoom, you can share the meeting info (link and dial in info), but with Google Meet you can dial someone into the call yourself +- In Zoom, only the meeting host (or co-hosts) can mute others, but in Google Meet anyone can mute anyone ## Google Meet Specifics -- Use Google Meet video chats in the browser (no download needed -- **You can add a Google Meet to a meeting invite** by clicking "Add conferencing" on the event management page. -- **You can also start or share a Google Meet from Slack** by typing `/hangout` -- **You can dial people into a Google Meet call.** -- A Google Meet invite dialog can generate a phone number that people can call +- Use Google Meet video chats in the browser (no download needed +- **You can add a Google Meet to a meeting invite** by clicking "Add conferencing" on the event management page. +- **You can also start or share a Google Meet from Slack** by typing `/hangout` +- **You can dial people into a Google Meet call.** +- A Google Meet invite dialog can generate a phone number that people can call ## Video Call Best Practices @@ -28,19 +28,19 @@ See [Video Call Best Practices](../../company-policies/new-hire-orientation/vide ## Google Meet Accessibility -- There are a lot of [great accessibility features](https://support.google.com/meet/answer/7313544) in Google Meet -- Learning how to [set up live captions](https://support.google.com/meet/answer/9300310) can help you engage with a client trouble hearing. This could be either because of a disability or because of a hardware malfunction. +- There are a lot of [great accessibility features](https://support.google.com/meet/answer/7313544) in Google Meet +- Learning how to [set up live captions](https://support.google.com/meet/answer/9300310) can help you engage with a client trouble hearing. This could be either because of a disability or because of a hardware malfunction. ## Available Commands -- /to, /msg \[user]\[message] - Sends an inline private message to the specified user. -- /shortcuts - Open keyboard shortcut help screen -- /help, /? - Displays a list of command descriptions and usages. -- /goto \[user] - Opens the profile of the specified user in a new tab. -- /mute - Mutes the audio of the caller. -- /unmute - Unmutes the audio of the caller. -- /vmute - Mutes the video of the caller. -- /unvmute - Unmutes the video of the caller. -- /users - Displays a list of participants in the video call. +- /to, /msg \[user]\[message] - Sends an inline private message to the specified user. +- /shortcuts - Open keyboard shortcut help screen +- /help, /? - Displays a list of command descriptions and usages. +- /goto \[user] - Opens the profile of the specified user in a new tab. +- /mute - Mutes the audio of the caller. +- /unmute - Unmutes the audio of the caller. +- /vmute - Mutes the video of the caller. +- /unvmute - Unmutes the video of the caller. +- /users - Displays a list of participants in the video call. ![Hangouts shortcuts](../../assets/images/hangout-shortcuts.png "Hangouts shortcuts") diff --git a/common-practices-tools/software-and-support/jira.md b/common-practices-tools/software-and-support/jira.md index 5810e97fc8..55b5b8db01 100644 --- a/common-practices-tools/software-and-support/jira.md +++ b/common-practices-tools/software-and-support/jira.md @@ -16,9 +16,9 @@ Typically the project manager/lead will take primary responsibility for creating Jira has Plan, Work and Report modes, which do more or less what they sound like: -- [Plan mode](https://confluence.atlassian.com/agile063/jira-agile-user-s-guide/using-a-board/using-plan-mode) is for prioritizing tickets and organizing sprints ahead of time. -- [Work mode](https://confluence.atlassian.com/agile065/jira-agile-user-s-guide/using-a-board/using-work-mode) is for progress during a sprint, for instance moving a ticket from "To Do" to "In Progress" to "Code Review", etc. -- [Report mode](https://confluence.atlassian.com/agile065/jira-agile-user-s-guide/using-a-board/using-report-mode) is for tracking progress and results with a variety of reporting options. +- [Plan mode](https://confluence.atlassian.com/agile063/jira-agile-user-s-guide/using-a-board/using-plan-mode) is for prioritizing tickets and organizing sprints ahead of time. +- [Work mode](https://confluence.atlassian.com/agile065/jira-agile-user-s-guide/using-a-board/using-work-mode) is for progress during a sprint, for instance moving a ticket from "To Do" to "In Progress" to "Code Review", etc. +- [Report mode](https://confluence.atlassian.com/agile065/jira-agile-user-s-guide/using-a-board/using-report-mode) is for tracking progress and results with a variety of reporting options. ## The Project Manager/lead's role in Jira @@ -30,14 +30,14 @@ Project managers/leads at CivicActions typically become very proficient in Jira. Jira's default workflow doesn't fit all projects, and project managers/leads usually work with their team to configure a workflow that team needs. Some questions to ask when optimizing the workflow might include: -- Is there a development branch? Does a workflow need to show when development gets merged into master? -- Are there documentation stages that need to happen post-development? -- What environments are in play for each stage in the workflow? Should the column names reflect that? -- Who's doing the QA? Same as code review? -- Does signoff or UAT require input from various stakeholders? -- How does Product Owner (or whomever is doing UAT) get alerted when something is ready for their review? -- Where do tickets reflecting design deliverables go when they are ready for review? -- What does the final "Done" column mean? Does it reflect something released to a production site? +- Is there a development branch? Does a workflow need to show when development gets merged into master? +- Are there documentation stages that need to happen post-development? +- What environments are in play for each stage in the workflow? Should the column names reflect that? +- Who's doing the QA? Same as code review? +- Does signoff or UAT require input from various stakeholders? +- How does Product Owner (or whomever is doing UAT) get alerted when something is ready for their review? +- Where do tickets reflecting design deliverables go when they are ready for review? +- What does the final "Done" column mean? Does it reflect something released to a production site? Some sample workflows for a variety of projects have been documented in [this google spreadsheet](https://docs.google.com/spreadsheets/d/1Ji0ZkO7GDK1lci1y_zYUqqlwiJe5FBmV9fsCe0T7GQY/edit#gid=0). @@ -57,9 +57,9 @@ Most tickets will benefit from careful estimates of how much work/time is involv ## Other resources, if you are new to Jira -- [Jira & Agile Project Management Video](http://youtu.be/NrHpXvDXVrw) (0:40 min) -- [Jira in a Nutshell Video](http://youtu.be/xrCJv0fTyR8) (0:04 min) -- [Jira Product Overview](http://youtu.be/tVCjr0HffVA) (0:05 min) -- [Jira 101](https://confluence.atlassian.com/jira064/jira-101-720412861.html) -- [Jira Agile Tutorial](https://confluence.atlassian.com/agile/jira-agile-user-s-guide/jira-agile-tutorials) -- [Planning and Estimating Work Tutorial](https://confluence.atlassian.com/agile/jira-agile-user-s-guide/jira-agile-tutorials/tutorial-planning-and-estimating-work-for-an-agile-team) +- [Jira & Agile Project Management Video](http://youtu.be/NrHpXvDXVrw) (0:40 min) +- [Jira in a Nutshell Video](http://youtu.be/xrCJv0fTyR8) (0:04 min) +- [Jira Product Overview](http://youtu.be/tVCjr0HffVA) (0:05 min) +- [Jira 101](https://confluence.atlassian.com/jira064/jira-101-720412861.html) +- [Jira Agile Tutorial](https://confluence.atlassian.com/agile/jira-agile-user-s-guide/jira-agile-tutorials) +- [Planning and Estimating Work Tutorial](https://confluence.atlassian.com/agile/jira-agile-user-s-guide/jira-agile-tutorials/tutorial-planning-and-estimating-work-for-an-agile-team) diff --git a/common-practices-tools/software-and-support/markdown.md b/common-practices-tools/software-and-support/markdown.md index de1712b648..5bc83f3cd3 100644 --- a/common-practices-tools/software-and-support/markdown.md +++ b/common-practices-tools/software-and-support/markdown.md @@ -12,11 +12,11 @@ There's a great tutorial [on the Commonmark website](http://commonmark.org/help/ ## More reading -- [markdowntutorial.com](http://markdowntutorial.com/) -- [GitHub markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) -- [MarkdownLivePreview.com](http://markdownlivepreview.com/) -- [Jira markdown cheatsheet](https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html) -- [Slack markdown cheatsheet](https://get.slack.help/hc/en-us/articles/202288908-Format-your-messages) +- [markdowntutorial.com](http://markdowntutorial.com/) +- [GitHub markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +- [MarkdownLivePreview.com](http://markdownlivepreview.com/) +- [Jira markdown cheatsheet](https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html) +- [Slack markdown cheatsheet](https://get.slack.help/hc/en-us/articles/202288908-Format-your-messages) ## Guidebook diff --git a/common-practices-tools/software-and-support/mural.md b/common-practices-tools/software-and-support/mural.md index 2ab3c5d384..2d5993df7e 100644 --- a/common-practices-tools/software-and-support/mural.md +++ b/common-practices-tools/software-and-support/mural.md @@ -42,11 +42,11 @@ If your project has a specific use case or if you have ideas for improving our M ## General Recommendations -- **Utilize Templates:** Start your murals with CivicActions-specific templates to save time and ensure consistency. -- **Collaborative Spaces:** Make full use of Mural's collaborative tools to engage every team member. -- **Stay Organized:** Keep your murals organized within folders and sub-folders to enhance accessibility and workflow. +- **Utilize Templates:** Start your murals with CivicActions-specific templates to save time and ensure consistency. +- **Collaborative Spaces:** Make full use of Mural's collaborative tools to engage every team member. +- **Stay Organized:** Keep your murals organized within folders and sub-folders to enhance accessibility and workflow. ## Additional Resources -- [Mural Docs](https://support.mural.co/s/) -- [Mural Slack channel](https://civicactions.slack.com/archives/C06PASS8S6M) +- [Mural Docs](https://support.mural.co/s/) +- [Mural Slack channel](https://civicactions.slack.com/archives/C06PASS8S6M) diff --git a/common-practices-tools/software-and-support/sauce-labs.md b/common-practices-tools/software-and-support/sauce-labs.md index 2ed48633a6..c7fd232cdc 100644 --- a/common-practices-tools/software-and-support/sauce-labs.md +++ b/common-practices-tools/software-and-support/sauce-labs.md @@ -2,17 +2,17 @@ CivicActions maintains a [Sauce Labs](https://saucelabs.com/) account for cross-browser and cross-device web and mobile app testing. -- Our plan supports interactive, live testing and developer tools access -- If needed we can also enable automated testing via [Selenium](https://www.seleniumhq.org/), [Cypress](https://www.cypress.io/), and [Playwright](https://playwright.dev/) -- This service is available to use internally and on client projects - - _Note_: some client projects maintain their own cross-browser testing tool subscriptions - in these cases, use the client/project provided tool. If you are unsure, ask your project manager or technical lead. +- Our plan supports interactive, live testing and developer tools access +- If needed we can also enable automated testing via [Selenium](https://www.seleniumhq.org/), [Cypress](https://www.cypress.io/), and [Playwright](https://playwright.dev/) +- This service is available to use internally and on client projects + - _Note_: some client projects maintain their own cross-browser testing tool subscriptions - in these cases, use the client/project provided tool. If you are unsure, ask your project manager or technical lead. ## Getting Started -- If you didn't already, click the "Verify Email" button in your invitaion e-mail (Subject: "\[Sauce Labs\] Please verify your email address") -- Go to [accounts.saucelabs.com](https://accounts.saucelabs.com/) and use the "Google" button to log in with your CivicActions e-mail address -- Go to the [Live -> Cross Browser](https://app.saucelabs.com/live/web-testing) menu and select your desired browser configuration -- Click the "Start Test" button to launch the browser +- If you didn't already, click the "Verify Email" button in your invitaion e-mail (Subject: "\[Sauce Labs\] Please verify your email address") +- Go to [accounts.saucelabs.com](https://accounts.saucelabs.com/) and use the "Google" button to log in with your CivicActions e-mail address +- Go to the [Live -> Cross Browser](https://app.saucelabs.com/live/web-testing) menu and select your desired browser configuration +- Click the "Start Test" button to launch the browser ### Testing Local Sites @@ -22,6 +22,6 @@ _Note_: if you need to test sites behind a client managed network boundary (such ## Getting Help -- The [Sauce Labs documentation](https://docs.saucelabs.com/) is a good place to start -- You can also ask in the #engineering-qa channel on Slack -- If you have access issues or account questions, open a [support ticket](README.md) +- The [Sauce Labs documentation](https://docs.saucelabs.com/) is a good place to start +- You can also ask in the #engineering-qa channel on Slack +- If you have access issues or account questions, open a [support ticket](README.md) diff --git a/common-practices-tools/software-and-support/slack.md b/common-practices-tools/software-and-support/slack.md index ebabe970e7..0082ef92a7 100644 --- a/common-practices-tools/software-and-support/slack.md +++ b/common-practices-tools/software-and-support/slack.md @@ -8,9 +8,9 @@ We use Slack for chatting with the team, whether as a whole, in smaller groups, ## Getting started -- Ensure your status is set to "available" in Slack when online and free to chat, and "away" when not -- Consider getting the Slack desktop app - either the native OS X / Windows one, or the Chrome app, which you can set up to run as a standalone app on system start up -- Make sure to add a photo of yourself for your Slack avatar +- Ensure your status is set to "available" in Slack when online and free to chat, and "away" when not +- Consider getting the Slack desktop app - either the native OS X / Windows one, or the Chrome app, which you can set up to run as a standalone app on system start up +- Make sure to add a photo of yourself for your Slack avatar ## Channels @@ -20,34 +20,34 @@ We default to open, so when in doubt, message the group in a public channel inst There are a wide variety of different channels you can join, from work-related to topic-related, including: -- **Mandatory channels** include: General, Announcements, How We Work, your Pod, your project channels, and your domain area channels (Engineering, Design, PM, etc) - - Note that the [Announcements channel](https://civicactions.slack.com/messages/announcements/details/) is for **announcements only**. All replies or conversation regarding announcements can transpire in the [General channel](https://civicactions.slack.com/messages/general/). Keeping announcements chatter to a minimum ensures that anyone who hasn't been paying attention to the General or other channels will be able to quickly locate important or not-to-be-missed information. -- Optional channels: you are welcome to poke around Slack and join any open channels, such as #pets - - to explore our channels, in the left-side navigation, select Channels > Manage > Browse channels +- **Mandatory channels** include: General, Announcements, How We Work, your Pod, your project channels, and your domain area channels (Engineering, Design, PM, etc) + - Note that the [Announcements channel](https://civicactions.slack.com/messages/announcements/details/) is for **announcements only**. All replies or conversation regarding announcements can transpire in the [General channel](https://civicactions.slack.com/messages/general/). Keeping announcements chatter to a minimum ensures that anyone who hasn't been paying attention to the General or other channels will be able to quickly locate important or not-to-be-missed information. +- Optional channels: you are welcome to poke around Slack and join any open channels, such as #pets + - to explore our channels, in the left-side navigation, select Channels > Manage > Browse channels ## Notifications -- To notify someone in particular, type **@name** with your message -- Consider using the word "ping" to check on the availability of someone -- If you want to call attention to everyone subscribed to channel, write **@channel** or **@group** -- To alert only those in a channel/group who are online, write **@here** -- You can adjust how and when you get notified by Slack activity by selecting Slack > Settings > Notifications +- To notify someone in particular, type **@name** with your message +- Consider using the word "ping" to check on the availability of someone +- If you want to call attention to everyone subscribed to channel, write **@channel** or **@group** +- To alert only those in a channel/group who are online, write **@here** +- You can adjust how and when you get notified by Slack activity by selecting Slack > Settings > Notifications ## Formatting your messages -- Wrap your text in single asterisks for **bold**, underscores for _italics_, `grave accents` for code, and start the line with a > sign to make it a block quote. Formatting in Slack is similar to Markdown.![Formatting in Slack](../../assets/images/slack-formatting.png "Slack Formatting") -- To wrap single line output, use one pair of backticks ( `Your code here`). For multiple lines, wrap with three backticks (`Your code here. Some more code.`). ![Wrapping code](../../assets/images/backticks.png "Wrapping code") +- Wrap your text in single asterisks for **bold**, underscores for _italics_, `grave accents` for code, and start the line with a > sign to make it a block quote. Formatting in Slack is similar to Markdown.![Formatting in Slack](../../assets/images/slack-formatting.png "Slack Formatting") +- To wrap single line output, use one pair of backticks ( `Your code here`). For multiple lines, wrap with three backticks (`Your code here. Some more code.`). ![Wrapping code](../../assets/images/backticks.png "Wrapping code") ### More formatting help -- [Formatting your messages](https://slack.zendesk.com/hc/en-us/articles/202288908-Formatting-your-message) -- [Creating a snippet](https://slack.zendesk.com/hc/en-us/articles/204145658-Creating-a-Snippet) +- [Formatting your messages](https://slack.zendesk.com/hc/en-us/articles/202288908-Formatting-your-message) +- [Creating a snippet](https://slack.zendesk.com/hc/en-us/articles/204145658-Creating-a-Snippet) ## Integration with Zoom and Google Meet -- Create a Zoom from Slack: type **/zoom** (will need to authorize) -- Create a Google Meet from Slack: type **/hangout** (will need to authorize the slack app in Meet/Hangout too) +- Create a Zoom from Slack: type **/zoom** (will need to authorize) +- Create a Google Meet from Slack: type **/hangout** (will need to authorize the slack app in Meet/Hangout too) ## Get support for Slack -- [Request internal support](README.md) for Slack issues +- [Request internal support](README.md) for Slack issues diff --git a/common-practices-tools/software-and-support/zoom.md b/common-practices-tools/software-and-support/zoom.md index a58f362608..97d2642a16 100644 --- a/common-practices-tools/software-and-support/zoom.md +++ b/common-practices-tools/software-and-support/zoom.md @@ -14,8 +14,8 @@ Login with your CivicActions email. You will see a link below the sign-in box th Most CivicActions employees have free Zoom accounts, which have enough features to participate and to host short meetings. Meeting hosts may need paid accounts, because free accounts are limited in two important ways: -- Meetings are limited to 40 minutes. -- No recording is possible. +- Meetings are limited to 40 minutes. +- No recording is possible. Paid accounts are available for those who need them regularly (once a week or so, or if you host a regular call that needs Zoom). If you need to host a longer meeting, or you need to record a meeting, you can either ask a project manager or someone you know has a paid account to host it for you, or you can request a paid account by opening an [IT ticket](README.md). @@ -27,20 +27,20 @@ See [Video Call Best Practices](../../company-policies/new-hire-orientation/vide There are a lot of [great accessibility features](https://explore.zoom.us/en/accessibility/) in Zoom. It is generally regarded as the most accessible video conferencing system. -- To enable live captioning the host must first set it up in their settings. +- To enable live captioning the host must first set it up in their settings. 1. Log in to your CivicActions issued Pro Zoom account 2. Click "Settings" in the left-hand navigation panel under "Profile" 3. Under "Meeting" click "In Meeting (Advanced)" then scroll down to find "Closed Captioning" -- Hosts can now can now enable/disable live captions in your Zoom meetings as can others in the meeting. -- There will also be a ["Live Transcript is available"](https://support.zoom.us/hc/en-us/articles/115004794983-Automatically-Transcribe-Cloud-Recordings-?_ga=2.177759968.494881096.1614756525-359380451.1613573452) message above the "CC Live Transcript" button when a Zoom host has enabled live transcriptions. This can be useful for people who want to review the discussion after the meeting is finished or for people who may have trouble understanding a fast conversation in their second language. +- Hosts can now can now enable/disable live captions in your Zoom meetings as can others in the meeting. +- There will also be a ["Live Transcript is available"](https://support.zoom.us/hc/en-us/articles/115004794983-Automatically-Transcribe-Cloud-Recordings-?_ga=2.177759968.494881096.1614756525-359380451.1613573452) message above the "CC Live Transcript" button when a Zoom host has enabled live transcriptions. This can be useful for people who want to review the discussion after the meeting is finished or for people who may have trouble understanding a fast conversation in their second language. ## Tips and shortcuts -- Zoom is the default video meeting tool for CivicActions as it easily allows participants to dial themselves in to the meeting. -- Slack has a shortcut to creating a meeting: enter "/zoom" in the channel or direct message where you want the meeting link to appear. -- Mute by default when joining: Settings > Audio and check "Always mute microphone when joining meeting" -- Optional video off by default when joining a new call (_but best practice is to turn video on during the meeting once joined_): Settings > Video and check "Turn off my video when joining meeting". -- Display participant names: Settings > Video and check "Always display participant's name on their video". -- Enable shortcuts outside of Zoom can be handy for (un)muting when Zoom is not your top window: Settings > Accessibility and select "Enable shortcuts even when the Zoom app is not in focus". -- Screen share Mac shortcut: Cmd + Shift + S. -- Screen share PC shortcut: Alt + Shift + S. +- Zoom is the default video meeting tool for CivicActions as it easily allows participants to dial themselves in to the meeting. +- Slack has a shortcut to creating a meeting: enter "/zoom" in the channel or direct message where you want the meeting link to appear. +- Mute by default when joining: Settings > Audio and check "Always mute microphone when joining meeting" +- Optional video off by default when joining a new call (_but best practice is to turn video on during the meeting once joined_): Settings > Video and check "Turn off my video when joining meeting". +- Display participant names: Settings > Video and check "Always display participant's name on their video". +- Enable shortcuts outside of Zoom can be handy for (un)muting when Zoom is not your top window: Settings > Accessibility and select "Enable shortcuts even when the Zoom app is not in focus". +- Screen share Mac shortcut: Cmd + Shift + S. +- Screen share PC shortcut: Alt + Shift + S. diff --git a/common-practices-tools/telephone.md b/common-practices-tools/telephone.md index 4f82072d37..75b8cfd266 100644 --- a/common-practices-tools/telephone.md +++ b/common-practices-tools/telephone.md @@ -4,7 +4,7 @@ title: Telephone use # Telephone Use -- There are times when a phone call in may also be necessary, such as when Wi-Fi is not available or to call in to Zoom -- Don't rely on speaker feature, but have a headset handy -- You may need to be called into a Google Hangout if you can't attend the video meeting -- Sharing your phone number with the client/PO is optional +- There are times when a phone call in may also be necessary, such as when Wi-Fi is not available or to call in to Zoom +- Don't rely on speaker feature, but have a headset handy +- You may need to be called into a Google Hangout if you can't attend the video meeting +- Sharing your phone number with the client/PO is optional diff --git a/company-policies/anti-harassment-policies.md b/company-policies/anti-harassment-policies.md index 11dcc9d4ba..fd57d3e805 100644 --- a/company-policies/anti-harassment-policies.md +++ b/company-policies/anti-harassment-policies.md @@ -17,10 +17,10 @@ Except where otherwise indicated, the term "harassment," as used in this policy, Under various state and federal laws, sexual harassment includes, but is not limited to, making unwanted sexual advances and requests for sexual favors where: -- Submission to such conduct or communication is either explicitly or implicitly made a term or condition of an individual's employment; or -- Submission to or rejection of such conduct or communication by an individual is used as a basis for employment decisions affecting such individual; or -- Such conduct or communication has the purpose or effect of unreasonably interfering with an individual's work performance or creates and/or perpetuates an intimidating, hostile, or offensive work environment. -- As defined by law, sexual harassment can also take the form of other unwelcome conduct or communication that has the purpose or effect of unreasonably interfering with an individual's work performance or creates and/or perpetuates an intimidating, hostile, or offensive work environment. Such other conduct or communication sometimes takes the form of verbal abuse of a sexual nature, unwanted touching, leering, sexual gestures, a display of sexually suggestive objects or images, sexually explicit or offensive jokes, stories, cartoons, nicknames, slurs, epithets, and other communications of a sexual nature. +- Submission to such conduct or communication is either explicitly or implicitly made a term or condition of an individual's employment; or +- Submission to or rejection of such conduct or communication by an individual is used as a basis for employment decisions affecting such individual; or +- Such conduct or communication has the purpose or effect of unreasonably interfering with an individual's work performance or creates and/or perpetuates an intimidating, hostile, or offensive work environment. +- As defined by law, sexual harassment can also take the form of other unwelcome conduct or communication that has the purpose or effect of unreasonably interfering with an individual's work performance or creates and/or perpetuates an intimidating, hostile, or offensive work environment. Such other conduct or communication sometimes takes the form of verbal abuse of a sexual nature, unwanted touching, leering, sexual gestures, a display of sexually suggestive objects or images, sexually explicit or offensive jokes, stories, cartoons, nicknames, slurs, epithets, and other communications of a sexual nature. ## What Are Other Kinds of Harassment? @@ -30,10 +30,10 @@ In addition to sexual harassment, the company prohibits all other harassment bas Harassment may take many forms, including the following conduct when based on the protected characteristics described above: -- Verbal. Epithets; derogatory comments, slurs, or name-calling; inappropriate jokes, emails or any other form of written communication, comments, noises, or remarks; repeated requests for dates, threats, propositions, unwelcome and unwanted correspondence, phone calls, and gifts; or other unwelcome attention. -- Physical. Assault; impeding or blocking movement; physical interference with normal work or movement; unwanted and unwarranted physical contact, such as touching, pinching, patting, grabbing, brushing against, or poking another employee's body. -- Visual. Abusive or patently offensive images (whether in photographs, posters, cartoons, drawings, paintings or other forms of imagery); displaying abusive or patently offensive images, writings or objects; ogling, staring at or directing attention to an employee's anatomy; leering; sexually oriented or suggestive gestures. -- Cyberstalking. Proscribed harassment using electronic communication, such as e-mail or instant messaging (IM), or messages posted to a website, blog, or discussion group. +- Verbal. Epithets; derogatory comments, slurs, or name-calling; inappropriate jokes, emails or any other form of written communication, comments, noises, or remarks; repeated requests for dates, threats, propositions, unwelcome and unwanted correspondence, phone calls, and gifts; or other unwelcome attention. +- Physical. Assault; impeding or blocking movement; physical interference with normal work or movement; unwanted and unwarranted physical contact, such as touching, pinching, patting, grabbing, brushing against, or poking another employee's body. +- Visual. Abusive or patently offensive images (whether in photographs, posters, cartoons, drawings, paintings or other forms of imagery); displaying abusive or patently offensive images, writings or objects; ogling, staring at or directing attention to an employee's anatomy; leering; sexually oriented or suggestive gestures. +- Cyberstalking. Proscribed harassment using electronic communication, such as e-mail or instant messaging (IM), or messages posted to a website, blog, or discussion group. Proscribed harassment can occur in one-on-one interactions or in group settings and can involve a co- worker, manager, vendor, customer, visitor, or agent of the company. Sexual harassment can also occur in the context of a relationship that was once consensual but has changed so that the behavior is no longer welcome by one party. It is impossible to specify every action or all words that could be interpreted as harassment. The examples listed above are not meant to be a complete list of objectionable behavior. Make a point of paying attention to others' reactions and stated requests and preferences, respecting their wishes, and treating them in a professional manner, regardless of gender, race, religion, nationality, age, sexual orientation, sexual identity or expression, or other protected characteristic. diff --git a/company-policies/expenses.md b/company-policies/expenses.md index c0d9671317..0895afa833 100644 --- a/company-policies/expenses.md +++ b/company-policies/expenses.md @@ -43,12 +43,12 @@ IMPORTANT NOTE: when your expense Request is approved, Unanet automatically chan ## Expense guidelines -- Treat company money like you would your own money, use it to work smarter and spend it with wisdom and care. -- Please book as early as possible - for flights and accommodation this can make a big difference! -- Consider AirBnB instead of hotels. If you are unsure of how many people can attend, getting a slightly larger AirBnB ahead of time is normally better than waiting and getting an AirBnB or hotel rooms last minute. -- Your Project Manager and the Finance Team will provide information about what is or isn't reimbursable. For example, if you prefer first class for a flight or want to add a leg for a vacation, then that wouldn't be reimbursable but the amount for an economy class return would. -- Reduce your footprint when possible and use public transit or shared Lyft Lines instead of single occupancy rides. -- If you are purchasing multiple "under $50" items in a short timespan, please consider that a single purchase and request approval first. +- Treat company money like you would your own money, use it to work smarter and spend it with wisdom and care. +- Please book as early as possible - for flights and accommodation this can make a big difference! +- Consider AirBnB instead of hotels. If you are unsure of how many people can attend, getting a slightly larger AirBnB ahead of time is normally better than waiting and getting an AirBnB or hotel rooms last minute. +- Your Project Manager and the Finance Team will provide information about what is or isn't reimbursable. For example, if you prefer first class for a flight or want to add a leg for a vacation, then that wouldn't be reimbursable but the amount for an economy class return would. +- Reduce your footprint when possible and use public transit or shared Lyft Lines instead of single occupancy rides. +- If you are purchasing multiple "under $50" items in a short timespan, please consider that a single purchase and request approval first. ### Travel expenses diff --git a/company-policies/new-hire-orientation/README.md b/company-policies/new-hire-orientation/README.md index 717155a557..787932455b 100644 --- a/company-policies/new-hire-orientation/README.md +++ b/company-policies/new-hire-orientation/README.md @@ -14,8 +14,8 @@ There are topics in this document that require more detail on how we implement p ### Learn more about CivicActions -- [Mission and Values](../../about-civicactions/mission-values.md) -- [Background and History](../../about-civicactions/README.md) +- [Mission and Values](../../about-civicactions/mission-values.md) +- [Background and History](../../about-civicactions/README.md) ## Onboarding process @@ -25,8 +25,8 @@ Welcome aboard! As part of the new employee onboarding process, we created an on ### General -- [Civicactions Guidebook in GitHub](https://github.com/CivicActions/guidebook/blob/master/README.md) -- [Bookmarks](bookmarks.md) (websites and tools we use regularly) +- [Civicactions Guidebook in GitHub](https://github.com/CivicActions/guidebook/blob/master/README.md) +- [Bookmarks](bookmarks.md) (websites and tools we use regularly) ### Human resources @@ -36,10 +36,10 @@ CivicActions uses TriNet for outsourcing benefits, payroll, and human resources **US employees** -- Health, dental and vision insurance - [TriNet](https://identity.trinet.com/) -- 401K - [July Services](https://www.julyservices.com/for-employees/start-here/) +- Health, dental and vision insurance - [TriNet](https://identity.trinet.com/) +- 401K - [July Services](https://www.julyservices.com/for-employees/start-here/) **Canadian employees** -- Health, dental and vision insurance - [Canada Life](https://my.canadalife.com/climsMyLogin) -- RRSP - [Canada Life](https://my.canadalife.com/climsMyLogin) +- Health, dental and vision insurance - [Canada Life](https://my.canadalife.com/climsMyLogin) +- RRSP - [Canada Life](https://my.canadalife.com/climsMyLogin) diff --git a/company-policies/new-hire-orientation/bookmarks.md b/company-policies/new-hire-orientation/bookmarks.md index f9cef8a684..a592466b7f 100644 --- a/company-policies/new-hire-orientation/bookmarks.md +++ b/company-policies/new-hire-orientation/bookmarks.md @@ -8,46 +8,46 @@ Links to websites we use regularly. ## CivicActions -- [Guidebook - GitHub](https://github.com/CivicActions/guidebook) -- [Website](https://civicactions.com/) +- [Guidebook - GitHub](https://github.com/CivicActions/guidebook) +- [Website](https://civicactions.com/) ## Social media -- [Twitter](https://twitter.com/CivicActions) -- [Facebook](https://www.facebook.com/CivicActions/) -- [LinkedIn](https://www.linkedin.com/company/civicactions/) +- [Twitter](https://twitter.com/CivicActions) +- [Facebook](https://www.facebook.com/CivicActions/) +- [LinkedIn](https://www.linkedin.com/company/civicactions/) ## Tools -- [Gmail](https://mail.google.com/) -- [Google Calendar](https://calendar.google.com) -- [Google Drive](https://drive.google.com/drive/u/0/) -- [Google Hangouts](https://hangouts.google.com/) -- [Slack](https://civicactions.slack.com) -- [Unanet](https://civicactions.unanet.biz) -- [Zoom](https://zoom.us/) -- [Invision](https://www.invisionapp.com/home) -- Atlassian's Jira for ticket management +- [Gmail](https://mail.google.com/) +- [Google Calendar](https://calendar.google.com) +- [Google Drive](https://drive.google.com/drive/u/0/) +- [Google Hangouts](https://hangouts.google.com/) +- [Slack](https://civicactions.slack.com) +- [Unanet](https://civicactions.unanet.biz) +- [Zoom](https://zoom.us/) +- [Invision](https://www.invisionapp.com/home) +- Atlassian's Jira for ticket management ### UX (User Experience/Design) -- [Figma](https://www.figma.com): for wireframing and prototyping -- [Mural](https://app.mural.co/signin): for collaborating -- [StoriesOnBoard](https://app.storiesonboard.com/login): for story mapping +- [Figma](https://www.figma.com): for wireframing and prototyping +- [Mural](https://app.mural.co/signin): for collaborating +- [StoriesOnBoard](https://app.storiesonboard.com/login): for story mapping ### Engineering tools -- [Sauce Labs](https://accounts.saucelabs.com/): for cross browser/device testing -- [GitLab](https://git.civicactions.net/) -- [Jenkins](http://ci.civicactions.net/) +- [Sauce Labs](https://accounts.saucelabs.com/): for cross browser/device testing +- [GitLab](https://git.civicactions.net/) +- [Jenkins](http://ci.civicactions.net/) ### Infrastructure/monitoring tools -- [StatusCake](https://app.statuscake.com/YourStatus.php) -- [OpsGenie](https://app.opsgenie.com/alert) -- [MxToolbox](https://mxtoolbox.com/SuperTool.aspx) -- [SSL Server Test](https://www.ssllabs.com/ssltest/) (Qualys) +- [StatusCake](https://app.statuscake.com/YourStatus.php) +- [OpsGenie](https://app.opsgenie.com/alert) +- [MxToolbox](https://mxtoolbox.com/SuperTool.aspx) +- [SSL Server Test](https://www.ssllabs.com/ssltest/) (Qualys) ### Accessibility -- [CivicActions Accessibility Site](https://accessibility.civicactions.com/guide/tools) +- [CivicActions Accessibility Site](https://accessibility.civicactions.com/guide/tools) diff --git a/company-policies/new-hire-orientation/buddy-program.md b/company-policies/new-hire-orientation/buddy-program.md index 44fe190c62..4fd55d3691 100644 --- a/company-policies/new-hire-orientation/buddy-program.md +++ b/company-policies/new-hire-orientation/buddy-program.md @@ -12,28 +12,28 @@ A buddy typically has been with CivicActions for at least six months to one year ## A Buddy's Responsibilities -- Set up regular 15 minute check in meetings with your new hire. The frequency of these should be twice per week for the first month, once per week in the second month, and on an as-needed basis after that. -- Facilitate conversations with your new hire during check ins, and answer any questions that come up. -- Pass along any notable issues, highlights, or questions to the onboarding manager to ensure they're addressed for future new hires. +- Set up regular 15 minute check in meetings with your new hire. The frequency of these should be twice per week for the first month, once per week in the second month, and on an as-needed basis after that. +- Facilitate conversations with your new hire during check ins, and answer any questions that come up. +- Pass along any notable issues, highlights, or questions to the onboarding manager to ensure they're addressed for future new hires. ## Tips for the Buddy -- Invite your new hire to any of your project meetings that you think might be helpful to have them observe -- Put yourself in your new hire's shoes. What important info do you wish you had known at that time? Share it! -- Conversation starters: - - What have you been learning during your onboarding sessions? - - In what areas do you feel strong/confident? - - In what areas do you feel unsure? - - How is your project going? Are you able to apply your onboarding learnings there? -- Share some "pro-tips" with your new hire. These are typically work shortcuts and tools that make life easier. Example: pressing the space bar in Zoom is an unmute button if you need to say something and are muted. +- Invite your new hire to any of your project meetings that you think might be helpful to have them observe +- Put yourself in your new hire's shoes. What important info do you wish you had known at that time? Share it! +- Conversation starters: + - What have you been learning during your onboarding sessions? + - In what areas do you feel strong/confident? + - In what areas do you feel unsure? + - How is your project going? Are you able to apply your onboarding learnings there? +- Share some "pro-tips" with your new hire. These are typically work shortcuts and tools that make life easier. Example: pressing the space bar in Zoom is an unmute button if you need to say something and are muted. ## Buddy To-Do Checklist -- Set up and attend regular check in meetings with your new hire -- Answer questions -- Stimulate conversation -- Review project playbooks and frameworks together +- Set up and attend regular check in meetings with your new hire +- Answer questions +- Stimulate conversation +- Review project playbooks and frameworks together ## Cross Functional Buddy -- A cross functional buddy is someone who is in a role opposite of your own. You may decide at some point to choose a cross functional role you'd like support in and this can become part of your [professional development](https://trello.com/b/p7FOD0Ju/template-professional-development-and-community-participation). +- A cross functional buddy is someone who is in a role opposite of your own. You may decide at some point to choose a cross functional role you'd like support in and this can become part of your [professional development](https://trello.com/b/p7FOD0Ju/template-professional-development-and-community-participation). diff --git a/company-policies/new-hire-orientation/elevator-pitch.md b/company-policies/new-hire-orientation/elevator-pitch.md index 95bce0850d..42fd7b0df3 100644 --- a/company-policies/new-hire-orientation/elevator-pitch.md +++ b/company-policies/new-hire-orientation/elevator-pitch.md @@ -26,15 +26,15 @@ Here's a sample: Some points to keep in mind: -- CivicActions - Open Technology & Design -- We care about sustainability for all - environmental and financial -- We improve digital services for government -- We use agile, DevOps, open data, and free software -- We want to create an open and accountable government -- We work to transform government with free and open technologies and agile processes -- We have an amazing company culture, and we're looking for new team members to join our mission! -- CivicActions works to transform government by providing digital services and open data using agile practices, user centered design, and free and open source software. We support the work of the [Technologists for the Public Good](https://www.publicgood.tech/) (previously Agile Gov Leadership) and are members of the [Digital Services Coalition](https://digitalservicescoalition.org/) and [Data Coalition](https://www.datacoalition.org/). -- CivicActions aims to transform government by empowering public sector agencies to deliver digital experiences that are innovative and rewarding. We are passionate civic technologists committed to a better world. +- CivicActions - Open Technology & Design +- We care about sustainability for all - environmental and financial +- We improve digital services for government +- We use agile, DevOps, open data, and free software +- We want to create an open and accountable government +- We work to transform government with free and open technologies and agile processes +- We have an amazing company culture, and we're looking for new team members to join our mission! +- CivicActions works to transform government by providing digital services and open data using agile practices, user centered design, and free and open source software. We support the work of the [Technologists for the Public Good](https://www.publicgood.tech/) (previously Agile Gov Leadership) and are members of the [Digital Services Coalition](https://digitalservicescoalition.org/) and [Data Coalition](https://www.datacoalition.org/). +- CivicActions aims to transform government by empowering public sector agencies to deliver digital experiences that are innovative and rewarding. We are passionate civic technologists committed to a better world. Here's a presentation about making your own elevator pitch: diff --git a/company-policies/new-hire-orientation/intro-open-source.md b/company-policies/new-hire-orientation/intro-open-source.md index 90b29b0fd1..61f088f685 100644 --- a/company-policies/new-hire-orientation/intro-open-source.md +++ b/company-policies/new-hire-orientation/intro-open-source.md @@ -32,8 +32,8 @@ For example, whitehouse.gov is powered by Drupal. Drupal publishes their softwar CivicActions uses and works with FOSS whenever possible, and we believe in because -- FOSS has zero lock-in -- FOSS is arguably more secure -- FOSS is easier to modify to suit customer needs -- FOSS aligns with other Agile practices prioritizing people over process -- We support the FOSS community via contributions +- FOSS has zero lock-in +- FOSS is arguably more secure +- FOSS is easier to modify to suit customer needs +- FOSS aligns with other Agile practices prioritizing people over process +- We support the FOSS community via contributions diff --git a/company-policies/new-hire-orientation/meetings-and-meeting-tools.md b/company-policies/new-hire-orientation/meetings-and-meeting-tools.md index 7ee1cd413c..0e26d4d387 100644 --- a/company-policies/new-hire-orientation/meetings-and-meeting-tools.md +++ b/company-policies/new-hire-orientation/meetings-and-meeting-tools.md @@ -16,40 +16,40 @@ Our weekly AHC includes everyone across CivicActions, and it's how the team diss ### AHC Overview -- We use Zoom for this - see [more about Zoom](../../common-practices-tools/software-and-support/zoom.md) -- Everyone on team is encouraged to join -- Invites with links are sent out the day of in [#announcements](https://civicactions.slack.com/messages/announcements) -- Meetings occur frequently as listed below +- We use Zoom for this - see [more about Zoom](../../common-practices-tools/software-and-support/zoom.md) +- Everyone on team is encouraged to join +- Invites with links are sent out the day of in [#announcements](https://civicactions.slack.com/messages/announcements) +- Meetings occur frequently as listed below #### Every Other Monday -- Length of call: 30 minutes -- Topics can range from a summary of a book, to staying balanced, to project overviews, to deep dive into a tool or module, etc -- This call is led by our peers and anyone can lead it! -- Want to sign up to present? Use the [AHC Trello board](https://trello.com/b/Yj3XOSWD/all-hands-call-ahc-planning) +- Length of call: 30 minutes +- Topics can range from a summary of a book, to staying balanced, to project overviews, to deep dive into a tool or module, etc +- This call is led by our peers and anyone can lead it! +- Want to sign up to present? Use the [AHC Trello board](https://trello.com/b/Yj3XOSWD/all-hands-call-ahc-planning) #### Once a Month -- Length of call: 1 hour -- Topics are usually company standing, sales pipeline, new hires, new projects, big announcements -- Led primarily by the management and sales teams +- Length of call: 1 hour +- Topics are usually company standing, sales pipeline, new hires, new projects, big announcements +- Led primarily by the management and sales teams ## Pod Calls Weekly pod calls help us stay in touch and in tune with each other. These are loosely arranged by time zone, and are generally casual and chatty in tone. -- Weekly pod calls are Vela, Pyxis, Hydra, Ursa, Aries -- There is a focus to connect with team members outside your project -- Pod calls help us feel connected with the team as a whole -- We discuss a topic of common interest or give project updates +- Weekly pod calls are Vela, Pyxis, Hydra, Ursa, Aries +- There is a focus to connect with team members outside your project +- Pod calls help us feel connected with the team as a whole +- We discuss a topic of common interest or give project updates ## Project Specific Meetings -- [Daily Scrum Call](../../common-practices-tools/agile/daily-scrum-calls.md) -- [Sprint Planning Meeting](../../common-practices-tools/agile/sprint-planning-meetings.md) -- [Backlog Refinement](../../common-practices-tools/agile/backlog-refinement.md) -- [Sprint Demo](../../common-practices-tools/agile/sprint-demo.md) -- [Sprint Retrospective](../../common-practices-tools/agile/sprint-retrospectives.md) +- [Daily Scrum Call](../../common-practices-tools/agile/daily-scrum-calls.md) +- [Sprint Planning Meeting](../../common-practices-tools/agile/sprint-planning-meetings.md) +- [Backlog Refinement](../../common-practices-tools/agile/backlog-refinement.md) +- [Sprint Demo](../../common-practices-tools/agile/sprint-demo.md) +- [Sprint Retrospective](../../common-practices-tools/agile/sprint-retrospectives.md) ## Practice Area Meetings diff --git a/company-policies/new-hire-orientation/people-planning.md b/company-policies/new-hire-orientation/people-planning.md index 7334c7a878..fc81e65b90 100644 --- a/company-policies/new-hire-orientation/people-planning.md +++ b/company-policies/new-hire-orientation/people-planning.md @@ -8,9 +8,9 @@ At CivicActions, we talk about people planning, not resource planning. People pl When discussing staffing for a new project, we consider: -- Does the skill set match? -- What does our forecast look like? -- Is the person willing and interested in the project? +- Does the skill set match? +- What does our forecast look like? +- Is the person willing and interested in the project? ## How we do people-planning @@ -30,6 +30,6 @@ Project managers are tasked with keeping Unanet People Plans up to date with tea The tools below help us to do people planning efficiently and we ask that team members update them on an annual basis: -- Skillsbase - We search Skillsbase to see who has skills for certain roles. -- Resumes - We use the templated CivicActions resumes to submit on new work when applicable. -- Development Plans - Team members create Development Plans in Culture Amp that help them and their managers find opportunities within the company to further growth. +- Skillsbase - We search Skillsbase to see who has skills for certain roles. +- Resumes - We use the templated CivicActions resumes to submit on new work when applicable. +- Development Plans - Team members create Development Plans in Culture Amp that help them and their managers find opportunities within the company to further growth. diff --git a/company-policies/new-hire-orientation/security-training.md b/company-policies/new-hire-orientation/security-training.md index bece785b2a..ebaa843f43 100644 --- a/company-policies/new-hire-orientation/security-training.md +++ b/company-policies/new-hire-orientation/security-training.md @@ -8,10 +8,10 @@ title: Security for everyone As a requirement for employment, every employee must review and acknowledge the [**CivicActions Security Policy**](../security.md) that includes: -- [Acceptable Use Policy](../security.md#acceptable-use-policy) -- [Access Policy](../security.md#access-policy) -- [Password Policy](../security.md#password-policy) -- [Server & Site Security](../../practice-areas/engineering/security-compliance.md#server-and-site-security) +- [Acceptable Use Policy](../security.md#acceptable-use-policy) +- [Access Policy](../security.md#access-policy) +- [Password Policy](../security.md#password-policy) +- [Server & Site Security](../../practice-areas/engineering/security-compliance.md#server-and-site-security) @@ -19,12 +19,12 @@ As a requirement for employment, every employee must review and acknowledge the Every employee and contractor at CivicActions practices safe and secure computing in the course of their work. We enhance our [Security Awareness with Tools](../../common-practices-tools/security/README.md) by: -- [Securing our Laptops](../../common-practices-tools/security/README.md#securing-your-laptop) -- [Using Password Management Tools](../../common-practices-tools/security/README.md#password-management-tools) -- [Using Multi-Factor Authentication](../../common-practices-tools/security/README.md#use-multi-factor-authentication-mfa) -- [Increasing our awareness of Phishing and Social Engineering](../../common-practices-tools/security/README.md#phishing-and-social-engineering) -- [Keeping our Personal Systems up-to-date](../../common-practices-tools/security/README.md#keep-your-systems-up-to-date) -- [Employing Disk Encryption and Secure Storage Management](../../common-practices-tools/security/README.md#disk-encryption-and-storage-management) +- [Securing our Laptops](../../common-practices-tools/security/README.md#securing-your-laptop) +- [Using Password Management Tools](../../common-practices-tools/security/README.md#password-management-tools) +- [Using Multi-Factor Authentication](../../common-practices-tools/security/README.md#use-multi-factor-authentication-mfa) +- [Increasing our awareness of Phishing and Social Engineering](../../common-practices-tools/security/README.md#phishing-and-social-engineering) +- [Keeping our Personal Systems up-to-date](../../common-practices-tools/security/README.md#keep-your-systems-up-to-date) +- [Employing Disk Encryption and Secure Storage Management](../../common-practices-tools/security/README.md#disk-encryption-and-storage-management) When moving through these steps, please update your entries in the [Security Checklist](https://docs.google.com/a/civicactions.net/spreadsheets/d/1t_LgXdkCNRzr5p36CV-cdzL8kJmUq_mHlsHWtMLm-Qg/edit?usp=sharing) -- if you need help, the Security Team has daily "Security Hours" scheduled in the calendar, or just ask in [`#general`](https://civicactions.slack.com/messages/general). @@ -38,9 +38,9 @@ Engineers and Project Managers and anyone directly involved in client site opera CivicActions Employees and Contractors regularly refresh their understanding of privacy regulations and security controls with the latest available information, including: -- Course: [Identifying and Safeguarding Personally Identifiable Information (PII)](https://securityawareness.usalearning.gov/piiv2/index.htm) -- Review: [CivicActions Employee/Contractor SecurityPolicy](../security.md) -- Internal: Yearly trainings/quizzes scheduled by the CivicActions Security Team +- Course: [Identifying and Safeguarding Personally Identifiable Information (PII)](https://securityawareness.usalearning.gov/piiv2/index.htm) +- Review: [CivicActions Employee/Contractor SecurityPolicy](../security.md) +- Internal: Yearly trainings/quizzes scheduled by the CivicActions Security Team ## Incident Response diff --git a/company-policies/new-hire-orientation/training-resources.md b/company-policies/new-hire-orientation/training-resources.md index cbac86570a..5351c5f9cc 100644 --- a/company-policies/new-hire-orientation/training-resources.md +++ b/company-policies/new-hire-orientation/training-resources.md @@ -8,27 +8,27 @@ As an CivicActions team member, you have access to these online training resourc ## BuildAModule -- Go to the [BuildAModule Google Calendar](https://calendar.google.com/calendar/b/1/embed?src=civicactions.net_3pqbiucmvmbt3nbmq259rj669s@group.calendar.google.com&ctz=America/Los_Angeles). -- Click the "+" button on the bottom right of this page, and add this calendar to your own civicactions.com Google Calendars. - - _Alternatively_: paste the following e-mail address into the "Other calendars" form on your civicactions.com Google Calendars page: -- Add your own booking to this calendar for the time you want to use it. To do this: -- Add an event to your own civicactions.com calendar - the event title can just be your name. -- In your event you must invite the "BuildAModule bookings (room)" user - this is what makes the booking. You can click over to "Find a time" to see available slots. -- Save the event and confirm that the calendar has accepted the invite (it will only accept non-conflicting invites). -- When your booked time is up, use the following credentials to log in: // +- Go to the [BuildAModule Google Calendar](https://calendar.google.com/calendar/b/1/embed?src=civicactions.net_3pqbiucmvmbt3nbmq259rj669s@group.calendar.google.com&ctz=America/Los_Angeles). +- Click the "+" button on the bottom right of this page, and add this calendar to your own civicactions.com Google Calendars. + - _Alternatively_: paste the following e-mail address into the "Other calendars" form on your civicactions.com Google Calendars page: +- Add your own booking to this calendar for the time you want to use it. To do this: +- Add an event to your own civicactions.com calendar - the event title can just be your name. +- In your event you must invite the "BuildAModule bookings (room)" user - this is what makes the booking. You can click over to "Find a time" to see available slots. +- Save the event and confirm that the calendar has accepted the invite (it will only accept non-conflicting invites). +- When your booked time is up, use the following credentials to log in: // > @todo [Add link to credentials](https://trello.com/c/dxKtjdYD/111-add-link-to-doc-with-drupalizeme-and-buildamodule-credentials) -- but do not include credentials here ## Drupalize.me -- Go to the [Drupalize.me Google Calendar](https://calendar.google.com/calendar/b/1/embed?src=civicactions.net_cebuchs4bgsjue2jbsv46hfeek@group.calendar.google.com&ctz=America/Los_Angeles). -- Click the "+" button on the bottom right of this page, and add this calendar to your own civicactions.com Google Calendars. - - _Alternatively_: paste the following e-mail address into the "Other calendars" form on your civicactions.com Google Calendars page: -- Add your own booking to this calendar for the time you want to use it. To do this: -- Add an event to your own civicactions.com calendar - the event title can just be your name. -- In your event you must invite the "Drupalize.me bookings (room)" user - this is what makes the booking. You can click over to "Find a time" to see available slots. -- Save the event and confirm that the calendar has accepted the invite (it will only accept non-conflicting invites). -- When your booked time is up, use the following credentials to log in: // +- Go to the [Drupalize.me Google Calendar](https://calendar.google.com/calendar/b/1/embed?src=civicactions.net_cebuchs4bgsjue2jbsv46hfeek@group.calendar.google.com&ctz=America/Los_Angeles). +- Click the "+" button on the bottom right of this page, and add this calendar to your own civicactions.com Google Calendars. + - _Alternatively_: paste the following e-mail address into the "Other calendars" form on your civicactions.com Google Calendars page: +- Add your own booking to this calendar for the time you want to use it. To do this: +- Add an event to your own civicactions.com calendar - the event title can just be your name. +- In your event you must invite the "Drupalize.me bookings (room)" user - this is what makes the booking. You can click over to "Find a time" to see available slots. +- Save the event and confirm that the calendar has accepted the invite (it will only accept non-conflicting invites). +- When your booked time is up, use the following credentials to log in: // > @todo [Add link to credentials](https://trello.com/c/dxKtjdYD/111-add-link-to-doc-with-drupalizeme-and-buildamodule-credentials) -- but do not include credentials here @@ -38,10 +38,10 @@ Here is a recommended reading list of books that people at CivicActions have fou ### Books / Ebooks -- ["Distributed Teams: The Art and Practice of Working Together While Physically Apart" by John O'Duinn](https://distributedteamsbook.com/buy/) -- ["Hiring Engineers" by Marianne Bellotti](https://leanpub.com/hiring-engineers) -- ["Kill It with Fire: Manage Aging Computer Systems (and Future Proof Modern Ones)" by Marianne Bellotti](https://www.penguinrandomhouse.com/books/667571/kill-it-with-fire-by-marianne-bellotti/) +- ["Distributed Teams: The Art and Practice of Working Together While Physically Apart" by John O'Duinn](https://distributedteamsbook.com/buy/) +- ["Hiring Engineers" by Marianne Bellotti](https://leanpub.com/hiring-engineers) +- ["Kill It with Fire: Manage Aging Computer Systems (and Future Proof Modern Ones)" by Marianne Bellotti](https://www.penguinrandomhouse.com/books/667571/kill-it-with-fire-by-marianne-bellotti/) ### Other Related Book Lists -- [Government and technology reading list](https://karpet.github.io/gov-tech-reading-list/) +- [Government and technology reading list](https://karpet.github.io/gov-tech-reading-list/) diff --git a/company-policies/new-hire-orientation/video-call-best-practices.md b/company-policies/new-hire-orientation/video-call-best-practices.md index f28c035d29..0eba0c608c 100644 --- a/company-policies/new-hire-orientation/video-call-best-practices.md +++ b/company-policies/new-hire-orientation/video-call-best-practices.md @@ -4,27 +4,27 @@ title: Video call best practices # Video Call Best Practices -- Be on time - please! Seconds matter. -- Add a photo to your account, so it shows up if your camera is off. -- Zoom has added a pronoun field. Please fill this in so that people are confident that they can communicate with you respectfully. These can be configured on https://zoom.us/profile -- We use the chat and screen sharing features. For certain calls like AHC we use Slack for chats so that folks who are watching a recording can participate also. Discussions in Slack are preserved and searchable, unlike those in Zoom. -- Turn off your camera or reduce bandwidth if the connection is poor. -- Use a headset or headphones instead of relying solely on the computer mic (computer mics can sometimes create echoes). -- Use your best judgment for video call dress, backgrounds, and effects. Most people turn off their video (face-mute) when eating. -- It's okay to mute others or ask them to mute themselves. It is a best practice to mute if primarily listening to a discussion. -- Be sure to let people know if you expect noise in your location and that you will be muting when not talking—dogs, construction, etc. -- When you see people talking who are on mute, it is a best practice to let them know. -- We can invite people outside of CivicActions. -- If someone hears an echo & you don't, then your computer is likely creating the echo. Try using headphones or plugging them in again. -- When appropriate and a screen isn't technically needed to be on a call, it's okay to face-mute and go for a walk or do another activity while listening or engaging in the discussion. Zoom has a mobile app that you can use for this purpose. Please let people know if you are doing this. +- Be on time - please! Seconds matter. +- Add a photo to your account, so it shows up if your camera is off. +- Zoom has added a pronoun field. Please fill this in so that people are confident that they can communicate with you respectfully. These can be configured on https://zoom.us/profile +- We use the chat and screen sharing features. For certain calls like AHC we use Slack for chats so that folks who are watching a recording can participate also. Discussions in Slack are preserved and searchable, unlike those in Zoom. +- Turn off your camera or reduce bandwidth if the connection is poor. +- Use a headset or headphones instead of relying solely on the computer mic (computer mics can sometimes create echoes). +- Use your best judgment for video call dress, backgrounds, and effects. Most people turn off their video (face-mute) when eating. +- It's okay to mute others or ask them to mute themselves. It is a best practice to mute if primarily listening to a discussion. +- Be sure to let people know if you expect noise in your location and that you will be muting when not talking—dogs, construction, etc. +- When you see people talking who are on mute, it is a best practice to let them know. +- We can invite people outside of CivicActions. +- If someone hears an echo & you don't, then your computer is likely creating the echo. Try using headphones or plugging them in again. +- When appropriate and a screen isn't technically needed to be on a call, it's okay to face-mute and go for a walk or do another activity while listening or engaging in the discussion. Zoom has a mobile app that you can use for this purpose. Please let people know if you are doing this. ## Video Preference Considerations -- We wish to host the most inclusive and welcoming spaces for all. Therefore, please use the camera option that works best for you. -- If you are comfortable with your camera on, then we encourage you to do so. However, turning cameras on is not required - we recognize that it does not work for everyone, which is ok. -- Don't assume that someone is less interested if their camera is off. Be aware that it may be a way for them to stay focused. -- Don't assume someone can recognize emotional content through words and vocal inflection alone. -- Some teams find that turning off their video after folks have settled in can help build trust and form deeper connections. Having a wall of faces to engage with can be draining and distracting. +- We wish to host the most inclusive and welcoming spaces for all. Therefore, please use the camera option that works best for you. +- If you are comfortable with your camera on, then we encourage you to do so. However, turning cameras on is not required - we recognize that it does not work for everyone, which is ok. +- Don't assume that someone is less interested if their camera is off. Be aware that it may be a way for them to stay focused. +- Don't assume someone can recognize emotional content through words and vocal inflection alone. +- Some teams find that turning off their video after folks have settled in can help build trust and form deeper connections. Having a wall of faces to engage with can be draining and distracting. ## Zoom fatigue diff --git a/company-policies/new-hire-orientation/virtual-workplace-basics.md b/company-policies/new-hire-orientation/virtual-workplace-basics.md index a1f8f7f521..5a36012e70 100644 --- a/company-policies/new-hire-orientation/virtual-workplace-basics.md +++ b/company-policies/new-hire-orientation/virtual-workplace-basics.md @@ -16,25 +16,25 @@ Check out this blog post: [How Remote Working Helps Us Live Our Dreams (And Get **When beginning your work day:** -- Check your CivicActions email and calendar for updates. -- Open Unanet so you remember to log your hours. -- Open Slack so your teammates can see that you are online and available. If you'd like, say good morning or "hello" in the [#general](https://civicactions.slack.com/messages/general/) channel when you log in. +- Check your CivicActions email and calendar for updates. +- Open Unanet so you remember to log your hours. +- Open Slack so your teammates can see that you are online and available. If you'd like, say good morning or "hello" in the [#general](https://civicactions.slack.com/messages/general/) channel when you log in. **When ending your work day:** -- Let your (project) team know that you're heading offline and ensure that no one needs your input before you go. -- Log your hours for the day in Unanet every day -- Close Slack (or set yourself to away)so that you don't appear to be online when you're not. +- Let your (project) team know that you're heading offline and ensure that no one needs your input before you go. +- Log your hours for the day in Unanet every day +- Close Slack (or set yourself to away)so that you don't appear to be online when you're not. ## Communication Best Practices -- **Err on the side of over-communication.** Proactive over-communication is better than under-communication, especially when you are working with a distributed team. It's good practice to share short updates on the progress of your work throughout the day. Ask questions and reach out, especially during training. +- **Err on the side of over-communication.** Proactive over-communication is better than under-communication, especially when you are working with a distributed team. It's good practice to share short updates on the progress of your work throughout the day. Ask questions and reach out, especially during training. -- **Assume team members are working asynchronously.** We use the chat program Slack for most communications. This ensures that all of our communication is documented, organized by channel, and easily searchable at a later time. See [Slack](../../common-practices-tools/software-and-support/slack.md) for related best practices. +- **Assume team members are working asynchronously.** We use the chat program Slack for most communications. This ensures that all of our communication is documented, organized by channel, and easily searchable at a later time. See [Slack](../../common-practices-tools/software-and-support/slack.md) for related best practices. -- **Use email for more formal communication.** In some cases, email may be a more appropriate communication channel than Slack; see [Email](../../common-practices-tools/software-and-support/email.md) for more information about email best practices. +- **Use email for more formal communication.** In some cases, email may be a more appropriate communication channel than Slack; see [Email](../../common-practices-tools/software-and-support/email.md) for more information about email best practices. -- **Follow the 30-minute rule.** We encourage engineers to follow a 30-minute rule when working on a technical challenge: don't spend more than 30 minutes banging your head against the wall on an issue - if you're blocked, ping/reach out to members of your team - i.e. an engineer reaching out in [#engineering](https://civicactions.slack.com/messages/engineering/). +- **Follow the 30-minute rule.** We encourage engineers to follow a 30-minute rule when working on a technical challenge: don't spend more than 30 minutes banging your head against the wall on an issue - if you're blocked, ping/reach out to members of your team - i.e. an engineer reaching out in [#engineering](https://civicactions.slack.com/messages/engineering/). ## Talking Time Zones @@ -44,10 +44,10 @@ There are some cases in which we reference other time zones, usually because of When in doubt use both PT & ET and make sure you're clarifying the time zone when you mention time! -- PT: Pacific Time -- MT: Mountain Time -- CT: Central Time -- ET: Eastern Time +- PT: Pacific Time +- MT: Mountain Time +- CT: Central Time +- ET: Eastern Time ## Virtual Workspaces @@ -56,8 +56,8 @@ in [Our Workspaces](https://trello.com/b/TJsUalpG/our-workspaces). Join the boar ## Tips for productivity while working remote -- **Create a schedule.** It doesn't really matter what your schedule is, as long as it's productive and everyone on the team knows when they can expect you to be working. The most important thing to is make your meetings, meet your deadlines, and communicate effectively. The hardest part of creating a schedule (especially when your team is all on different time zones) is having non-working hours and (mostly) sticking to them. It's important to also schedule this offline time to maintain a balance from office and home – so when my work day is done, I step away from the computer. -- **Stay connected.** Solid communication and transparency are key factors in a well-oiled team. Staying clear and efficiently connected are even more important when you work in a distributed team. There are lots of tools for communicating online, and one that we use the most is Slack. This is a way for our team to stay connected – and not just about work. Having specific channels for your project offer a searchable, archived, and visible spot for all communication about the project – and this is beneficial over the traditional one-off hallway conversations that are easily lost or forgotten. Having this "online community" on Slack also offers us a separate-from-projects-place to keep in touch in other areas outside of work – think of it as the water cooler talk in an office. We have channels including "random", "song of the day", and "health" so that we have a place to talk about things beyond work and a way to be more connected as a team and show off our sense of humors. -- **Prepare for the day.** Start your day like you would if you were going into the office. Get up, shower, eat breakfast, drink coffee, and get dressed for the day. Not only will looking presentable be nice for your daily video meetings, but it also creates a sense of "work mode" to get into the day's groove. This is not to say you can't be comfortable too – occasionally working in a blazer and yoga pants can be liberating! -- **Keep an eye on your balance.** In every scrum meeting, each person indicates their work/life balance score. If you're feeling low and bogged down in work (or life), you can count on feeling supported by your team. We encourage each other to find a happy balance, and for some of us that means we need frequent breaks or to take a daily walk; while others find solace being heads-down in the screen all day. When you work from home, it's important to keep yourself in check and make sure you're aware of your balance. -- **Make an office.** And make it yours. Most of us have both laptops and desktops, so we benefit from having a dedicated office space, but also being able to take our meeting to the couch or backyard. The most important thing is to make sure your office space fits you (however you like to work). When you build your own space, you have the benefits of making it just right – standing desk, walking desk, laptop on the couch, the options are near endless to make sure you're the most productive! +- **Create a schedule.** It doesn't really matter what your schedule is, as long as it's productive and everyone on the team knows when they can expect you to be working. The most important thing to is make your meetings, meet your deadlines, and communicate effectively. The hardest part of creating a schedule (especially when your team is all on different time zones) is having non-working hours and (mostly) sticking to them. It's important to also schedule this offline time to maintain a balance from office and home – so when my work day is done, I step away from the computer. +- **Stay connected.** Solid communication and transparency are key factors in a well-oiled team. Staying clear and efficiently connected are even more important when you work in a distributed team. There are lots of tools for communicating online, and one that we use the most is Slack. This is a way for our team to stay connected – and not just about work. Having specific channels for your project offer a searchable, archived, and visible spot for all communication about the project – and this is beneficial over the traditional one-off hallway conversations that are easily lost or forgotten. Having this "online community" on Slack also offers us a separate-from-projects-place to keep in touch in other areas outside of work – think of it as the water cooler talk in an office. We have channels including "random", "song of the day", and "health" so that we have a place to talk about things beyond work and a way to be more connected as a team and show off our sense of humors. +- **Prepare for the day.** Start your day like you would if you were going into the office. Get up, shower, eat breakfast, drink coffee, and get dressed for the day. Not only will looking presentable be nice for your daily video meetings, but it also creates a sense of "work mode" to get into the day's groove. This is not to say you can't be comfortable too – occasionally working in a blazer and yoga pants can be liberating! +- **Keep an eye on your balance.** In every scrum meeting, each person indicates their work/life balance score. If you're feeling low and bogged down in work (or life), you can count on feeling supported by your team. We encourage each other to find a happy balance, and for some of us that means we need frequent breaks or to take a daily walk; while others find solace being heads-down in the screen all day. When you work from home, it's important to keep yourself in check and make sure you're aware of your balance. +- **Make an office.** And make it yours. Most of us have both laptops and desktops, so we benefit from having a dedicated office space, but also being able to take our meeting to the couch or backyard. The most important thing is to make sure your office space fits you (however you like to work). When you build your own space, you have the benefits of making it just right – standing desk, walking desk, laptop on the couch, the options are near endless to make sure you're the most productive! diff --git a/company-policies/prohibited-hardware-and-software.md b/company-policies/prohibited-hardware-and-software.md index 85cebe0d94..3f55dec102 100644 --- a/company-policies/prohibited-hardware-and-software.md +++ b/company-policies/prohibited-hardware-and-software.md @@ -8,15 +8,15 @@ CivicActions has established a list of hardware and software that is prohibited The following is the list of hardware and software that is prohibited to use based on FAR requirements: -- [FAR 52.204-23](https://www.acquisition.gov/far/52.204-23) - Prohibition of hardware, software, and services provided by Kaspersky Lab; **Kaspersky** is primarily known for making antivirus software. -- [FAR 52.204-24](https://www.acquisition.gov/far/52.204-24) - Prohibition of telecommunications (such as mobile phones) and video surveillance services or equipment manufactured by: - - **Huawei** Technologies Company - - **ZTE** Corporation - - Hytera Communications - - Hangzhou **Hikvision** Digital Technology Company - - Dahua Technology Company - - Any subsidiary or affiliate -- [FAR 52.204-27](https://www.acquisition.gov/far/52.204-27) - Prohibition of ByteDance application, including social-media service and application **TikTok**. +- [FAR 52.204-23](https://www.acquisition.gov/far/52.204-23) - Prohibition of hardware, software, and services provided by Kaspersky Lab; **Kaspersky** is primarily known for making antivirus software. +- [FAR 52.204-24](https://www.acquisition.gov/far/52.204-24) - Prohibition of telecommunications (such as mobile phones) and video surveillance services or equipment manufactured by: + - **Huawei** Technologies Company + - **ZTE** Corporation + - Hytera Communications + - Hangzhou **Hikvision** Digital Technology Company + - Dahua Technology Company + - Any subsidiary or affiliate +- [FAR 52.204-27](https://www.acquisition.gov/far/52.204-27) - Prohibition of ByteDance application, including social-media service and application **TikTok**. ## Policy diff --git a/company-policies/security.md b/company-policies/security.md index dad83889b8..aec9e7116b 100644 --- a/company-policies/security.md +++ b/company-policies/security.md @@ -9,20 +9,20 @@ CivicActions has established the following policy to safeguard the security, con ## Our primary goals -- Protect clients' confidential and personal information; -- Reduce potential liability of CivicActions; -- Craft a consistent policy that is easy to understand, implement and follow; -- Educate/disseminate our best practices for security throughout the CivicActions community; -- Demonstrate to clients that we are trustworthy and satisfy contractual requirements for security. +- Protect clients' confidential and personal information; +- Reduce potential liability of CivicActions; +- Craft a consistent policy that is easy to understand, implement and follow; +- Educate/disseminate our best practices for security throughout the CivicActions community; +- Demonstrate to clients that we are trustworthy and satisfy contractual requirements for security. ## Confidential Information Agreement CivicActions does most things out in the open, and we strive to reduce the amount of Confidential Information (defined below) we get from third parties. Despite that, during your time as an employee or independent contractor you will be exposed to certain Confidential Information owned by CivicActions, owned by third parties, or provided to us by users and governed by our privacy policy. This section of the Agreement describes the responsibilities you have with regards to such information. Accordingly, you agree that Confidential Information: -- is owned by CivicActions, or (where appropriate) by the third party from whom it originated -- will only be used as necessary to perform your job -- will be protected by you with reasonable measures (such as not letting it out of your control) -- will not be disclosed to anyone outside of CivicActions +- is owned by CivicActions, or (where appropriate) by the third party from whom it originated +- will only be used as necessary to perform your job +- will be protected by you with reasonable measures (such as not letting it out of your control) +- will not be disclosed to anyone outside of CivicActions You further agree that you will promptly notify your manager if you know of unauthorized use of Confidential Information. @@ -41,12 +41,12 @@ Not all information or material you encounter is confidential information. Gener From the point of view of a typical client project, this means that: -- Database exports should always be treated as confidential, since these may contain personal information that is not publicly available. -- The uploaded files directory may need to be treated as confidential if the client site has any access-controlled content. -- The site source code can normally be treated as non-confidential, unless this includes proprietary code from the client or 3rd parties. -- The contents of the project management site (e.g. Jira, Mural, etc.), e-mail lists and related communication tools, will normally contain a mixture of confidential and non-confidential information: - - Information authored by clients or 3rd parties should generally be treated as confidential, unless it is clearly public-facing, and then its use other than as set forth in the engagement agreement may still require client permission. If in doubt, ask your supervisor or the legal team. - - Project management material can be sourced for distribution or repurposing, but should be first reviewed and redacted, if needed, to ensure no confidential information remains. +- Database exports should always be treated as confidential, since these may contain personal information that is not publicly available. +- The uploaded files directory may need to be treated as confidential if the client site has any access-controlled content. +- The site source code can normally be treated as non-confidential, unless this includes proprietary code from the client or 3rd parties. +- The contents of the project management site (e.g. Jira, Mural, etc.), e-mail lists and related communication tools, will normally contain a mixture of confidential and non-confidential information: + - Information authored by clients or 3rd parties should generally be treated as confidential, unless it is clearly public-facing, and then its use other than as set forth in the engagement agreement may still require client permission. If in doubt, ask your supervisor or the legal team. + - Project management material can be sourced for distribution or repurposing, but should be first reviewed and redacted, if needed, to ensure no confidential information remains. If you are unsure about the confidentiality of a piece of information you should ask someone who is able to give a qualified answer (if in doubt who this is, consult with the legal team) - in the meantime, work from the assumption that it is confidential. @@ -62,27 +62,27 @@ There are also a number of security concerns with non-confidential information. It is important that our information technology systems, service and network infrastructure are used in ways that maintain: -- Security from unauthorized access and use -- Data integrity -- Compliance with the law -- Compliance with our hosting provider(s) acceptable use policies +- Security from unauthorized access and use +- Data integrity +- Compliance with the law +- Compliance with our hosting provider(s) acceptable use policies CivicActions IT services provide a number of general user accounts. This includes: -- CivicActions GSuite Google Apps (Gmail, Hangouts, Docs, Drive, etc.) -- Web-based collaboration accounts such as - - Our home site - - Intranet (internal team collaboration) - - Project management site (Jira, GitLab, ...) - - Third party collaboration tools (such as Slack, Mural, Zoom, ...) +- CivicActions GSuite Google Apps (Gmail, Hangouts, Docs, Drive, etc.) +- Web-based collaboration accounts such as + - Our home site + - Intranet (internal team collaboration) + - Project management site (Jira, GitLab, ...) + - Third party collaboration tools (such as Slack, Mural, Zoom, ...) Usage of CivicActions user accounts should be as follows: -- Usage must be directly related to your work with CivicActions - personal use (including personal projects) must be approved in advance by the CTO. -- Use in any way harmful to CivicActions or our clients is forbidden. -- Automatic forwarding of CivicActions email to an outside account (e.g. Slack or a personal gmail.com account) is prohibited. -- Confidential information (other than personal information) should only be stored in areas restricted by access control, such as within a client's VPN or sometimes on a CivicActions Google Share Drive. -- Binary software or executable files should not be distributed internally as we do not have anti-virus scanning in place. +- Usage must be directly related to your work with CivicActions - personal use (including personal projects) must be approved in advance by the CTO. +- Use in any way harmful to CivicActions or our clients is forbidden. +- Automatic forwarding of CivicActions email to an outside account (e.g. Slack or a personal gmail.com account) is prohibited. +- Confidential information (other than personal information) should only be stored in areas restricted by access control, such as within a client's VPN or sometimes on a CivicActions Google Share Drive. +- Binary software or executable files should not be distributed internally as we do not have anti-virus scanning in place. In addition to user accounts we provide developer and system administrator access to system and service accounts, such as administrator web-access and SSH access to client sites, version control systems such as Git and MySQL database access. Usage of these accounts is covered in the [Engineering Security and Compliance](../practice-areas/engineering/security-compliance.md) guidelines. @@ -90,27 +90,27 @@ In addition to user accounts we provide developer and system administrator acces The security of our systems is only as strong as the weakest link. Hence it is important that all devices that connect and are authenticating to any CivicActions IT system are as secure as possible. Specifically: -- This includes access to web based accounts, such as our intranet, as well as developer accounts. -- This covers both desktop and laptop machines, as well as devices such as mobile phones and network routers (including home/office Internet gateways). This also includes 3rd party sourced servers/services that employees and contractors may employ as part of their workflow. -- CivicActions is responsible for maintaining the security of our own systems, as well as supporting computers or other devices that may be provided to staff as a part of their employment. -- Employees and contractors are responsible for maintaining their own systems to the highest standards of security. This includes (but is not limited to) the standards described in this document. -- The civicactions.com Google docs and domain must be accessed via your civicactions.com email address. In particular, it is not permitted to add a personal email address to shared civicactions.com domain Google docs. +- This includes access to web based accounts, such as our intranet, as well as developer accounts. +- This covers both desktop and laptop machines, as well as devices such as mobile phones and network routers (including home/office Internet gateways). This also includes 3rd party sourced servers/services that employees and contractors may employ as part of their workflow. +- CivicActions is responsible for maintaining the security of our own systems, as well as supporting computers or other devices that may be provided to staff as a part of their employment. +- Employees and contractors are responsible for maintaining their own systems to the highest standards of security. This includes (but is not limited to) the standards described in this document. +- The civicactions.com Google docs and domain must be accessed via your civicactions.com email address. In particular, it is not permitted to add a personal email address to shared civicactions.com domain Google docs. Before connecting and authenticating to any CivicActions IT system or storing confidential information on your systems, all users must ensure that: -- Operating systems, and all software that makes network connections (such as web browsers), or opens files that have been downloaded from the Internet (such as PDF readers) is patched or updated to resolve critical publicly known vulnerabilities, or, when an older version of a program is used on purpose (such as for interoperability testing), it is run in a sandbox (typically a virtual machine). -- Systems vulnerable to malware infections (primarily Windows, but may include other systems and mobile devices) are running a high-quality virus scanner (such as Avast or ClamAV) that automatically updates its virus definitions at least every 24 hours, detects malware in a real-time fashion, and completes a full system scan at least every week. In addition, Windows users are expected to run a general malware scanner (which may be integrated into the virus scanner, or may be separate, such as Adaware or TotalAV) that detects accidentally installed malware that does not qualify as a virus. -- A firewall is configured to block all unsolicited incoming connections to systems that store confidential information. This can be a network router NAT based firewall, or a software based firewall running on your local machine. This applies to all operating systems. - - For laptops that are used in hostile network environments (including public places such as cafes or airports) a software based firewall is mandatory. - - For users of Unix based systems, such as GNU/Linux and OS X, it is acceptable to open port 22 to allow external SSH access to home/office computers, as long as these systems are up-to-date with security patches and they use strong account passwords or SSH keys. - - It is particularly important to ensure that network shares, databases and local development sandbox versions of web sites are not publicly visible, both when working from home/office and when working in public places. -- User accounts on all systems must be password protected (using passwords that adhere to our password policy) and require entering the password on initial startup, as well as on resume from "sleep" mode. -- Whenever practical, work should be done from under a relatively non-privileged (user) account, not from an account with administrative privileges on the computer. Working under the latter is more likely to result in unintended installation of malicious software that would be harder for an anti-virus program to detect and cure. Thus, even if you're the only person using a computer (such as a laptop), it is a good practice to create two accounts on the computer: a "user" and an "administrator", and use the "user" account for most activities. -- Untrusted software should not be installed. This includes software you have never heard of, as well as known software that was downloaded from sources other than the author's site or a trusted, established repository. -- Be cautious opening e-mail attachments or files sent over instant messengers or similar systems. Even if the attachment is from a contact you recognize, if it is unexpected and does not indicate a project or discussion you recognize it is wise to e-mail the person separately to confirm that they sent the message. The reason for this is that it is common for malware to use e-mail software contact lists to send e-mails masquerading as a known contact with the malware attached. -- Do not access CivicActions IT systems using an untrusted computer (for example an Internet café or library system). This is because these systems can easily be infected with malware that transmit user activity to a 3rd party. -- If technically possible, additional protections such as encryption of your home directory (with a strong passphrase not reused for another purpose) and "remote wipe" of lost mobile devices are encouraged. -- When connected to wired or wireless Internet connections associated with CivicActions (for example while at company sprints/retreats or when visiting client site offices), users are expected to follow the appropriate terms and conditions of that provider, and to avoid initiating network traffic (e.g. by visiting specific websites or running file sharing software) that may bring our reputation into question. +- Operating systems, and all software that makes network connections (such as web browsers), or opens files that have been downloaded from the Internet (such as PDF readers) is patched or updated to resolve critical publicly known vulnerabilities, or, when an older version of a program is used on purpose (such as for interoperability testing), it is run in a sandbox (typically a virtual machine). +- Systems vulnerable to malware infections (primarily Windows, but may include other systems and mobile devices) are running a high-quality virus scanner (such as Avast or ClamAV) that automatically updates its virus definitions at least every 24 hours, detects malware in a real-time fashion, and completes a full system scan at least every week. In addition, Windows users are expected to run a general malware scanner (which may be integrated into the virus scanner, or may be separate, such as Adaware or TotalAV) that detects accidentally installed malware that does not qualify as a virus. +- A firewall is configured to block all unsolicited incoming connections to systems that store confidential information. This can be a network router NAT based firewall, or a software based firewall running on your local machine. This applies to all operating systems. + - For laptops that are used in hostile network environments (including public places such as cafes or airports) a software based firewall is mandatory. + - For users of Unix based systems, such as GNU/Linux and OS X, it is acceptable to open port 22 to allow external SSH access to home/office computers, as long as these systems are up-to-date with security patches and they use strong account passwords or SSH keys. + - It is particularly important to ensure that network shares, databases and local development sandbox versions of web sites are not publicly visible, both when working from home/office and when working in public places. +- User accounts on all systems must be password protected (using passwords that adhere to our password policy) and require entering the password on initial startup, as well as on resume from "sleep" mode. +- Whenever practical, work should be done from under a relatively non-privileged (user) account, not from an account with administrative privileges on the computer. Working under the latter is more likely to result in unintended installation of malicious software that would be harder for an anti-virus program to detect and cure. Thus, even if you're the only person using a computer (such as a laptop), it is a good practice to create two accounts on the computer: a "user" and an "administrator", and use the "user" account for most activities. +- Untrusted software should not be installed. This includes software you have never heard of, as well as known software that was downloaded from sources other than the author's site or a trusted, established repository. +- Be cautious opening e-mail attachments or files sent over instant messengers or similar systems. Even if the attachment is from a contact you recognize, if it is unexpected and does not indicate a project or discussion you recognize it is wise to e-mail the person separately to confirm that they sent the message. The reason for this is that it is common for malware to use e-mail software contact lists to send e-mails masquerading as a known contact with the malware attached. +- Do not access CivicActions IT systems using an untrusted computer (for example an Internet café or library system). This is because these systems can easily be infected with malware that transmit user activity to a 3rd party. +- If technically possible, additional protections such as encryption of your home directory (with a strong passphrase not reused for another purpose) and "remote wipe" of lost mobile devices are encouraged. +- When connected to wired or wireless Internet connections associated with CivicActions (for example while at company sprints/retreats or when visiting client site offices), users are expected to follow the appropriate terms and conditions of that provider, and to avoid initiating network traffic (e.g. by visiting specific websites or running file sharing software) that may bring our reputation into question. If a system is believed to be compromised, either through theft, loss, remote access, virus/malware infection, CivicActions IT should be informed immediately. @@ -124,10 +124,10 @@ We strongly recommend employing [Multi-Factor Authentication](../common-practice All passwords at CivicActions must follow this policy, including passwords used for: -- Personal computers or devices that access CivicActions or client services or store confidential information. -- Your password manager, PGP and SSH encryption keys. -- Accounts on any CivicActions or client site or service. -- Accounts on 3rd party vendor sites. +- Personal computers or devices that access CivicActions or client services or store confidential information. +- Your password manager, PGP and SSH encryption keys. +- Accounts on any CivicActions or client site or service. +- Accounts on 3rd party vendor sites. CivicActions requires that you employ a unique, strong password for every service that you log into. For this reason, CivicActions requires use of a [Password Manager](../common-practices-tools/security/README.md#password-management-tools). @@ -135,7 +135,7 @@ CivicActions requires that you employ a unique, strong password for every servic If you suspect a password has been compromised (for example, it was accidentally typed into an unencrypted chat session), [report the incident](../common-practices-tools/security/incidents.md#reporting-an-incident) immediately - the Security Team will provide support. It is usually good practice to change the password yourself if possible. -- This includes the case when a client sends a name/password pair in the clear in an email. +- This includes the case when a client sends a name/password pair in the clear in an email. ## Mobile Device Security @@ -158,10 +158,10 @@ Securing mobile devices used for CivicActions work is crucial for safeguarding s We maintain a [Security Awareness and Tools](../common-practices-tools/security/README.md) document that dives deeper into these and some additional topics, including: -- Password Management Tools -- Multi-Factor Authentication -- Phishing and Social Engineering -- Backups -- Secure Delete Files and Wiping Disks +- Password Management Tools +- Multi-Factor Authentication +- Phishing and Social Engineering +- Backups +- Secure Delete Files and Wiping Disks Finally, in addition to the above policies, CivicActions Engineers -- who may have elevated privileges in specific environments -- are required to align with the [Engineering Security and Compliance](../practice-areas/engineering/security-compliance.md) guidelines. diff --git a/company-policies/sustainability.md b/company-policies/sustainability.md index 4b89cb4cd2..5a104f1648 100644 --- a/company-policies/sustainability.md +++ b/company-policies/sustainability.md @@ -13,11 +13,11 @@ Sustainability has been one of the consistent threads in our work over the last ### We believe -- Our ecosystem is interdependent -- Using science, we can understand environmental systems and effectively address issues -- Promoting habitat and diversity, supports ecological systems -- Environmental challenges have social and political impacts -- The impact of climate change will disproportionately affect disadvantaged groups +- Our ecosystem is interdependent +- Using science, we can understand environmental systems and effectively address issues +- Promoting habitat and diversity, supports ecological systems +- Environmental challenges have social and political impacts +- The impact of climate change will disproportionately affect disadvantaged groups ## CivicActions' Sustainability Goals and Policies @@ -69,8 +69,8 @@ Please engage in the #sustainability Slack channel. ## Resources -- [Comprehensive Guide: How to write an Effective Employee Sustainability Handbook](https://www.awardaroo.io/resources/comprehensive-guide-how-to-write-an-effective-employee-sustainability-handbook) -- [Web Sustainability Guidelines](https://w3c.github.io/sustyweb/) +- [Comprehensive Guide: How to write an Effective Employee Sustainability Handbook](https://www.awardaroo.io/resources/comprehensive-guide-how-to-write-an-effective-employee-sustainability-handbook) +- [Web Sustainability Guidelines](https://w3c.github.io/sustyweb/) ## Conclusion diff --git a/company-policies/timekeeping-policies.md b/company-policies/timekeeping-policies.md index c9932bfdc6..76d6c8143e 100644 --- a/company-policies/timekeeping-policies.md +++ b/company-policies/timekeeping-policies.md @@ -103,27 +103,27 @@ A cost is reasonable if, in its nature and amount, it does not exceed that which It is the policy of CivicActions to ensure accurate timekeeping and subsequent invoicing of all labor costs to its customers, either directly or indirectly. The procedures provided in this Policy, are to provide a formal process for recording labor associated with Direct and Indirect cost objectives. It is the responsibility of CivicActions' Leadership and all Team Members, to abide by and promote the following principles which serve as guiding principles throughout this Policy: -- Promote an environment of accurate and compliant timekeeping practices -- Establish appropriate, relevant, and compliant timekeeping policies and procedures which are maintained -- Maintain accurate and timely timesheets, for all CivicActions' Team Members, to support accurate and compliant invoicing to all CivicActions' customers -- All CivicActions' Team Members are trained upon hire with annual refresher trainings regarding accurate timekeeping practices and policies -- All CivicActions' Team Members are responsible for submitting accurate, compliant, and reasonable timesheets -- CivicActions' Project Managers and Managers must review all time / timesheets, for completeness, accuracy, and reasonableness -- Appropriate segregation of duties exists between those individuals who are responsible for administrative timekeeping management and the processing of payroll +- Promote an environment of accurate and compliant timekeeping practices +- Establish appropriate, relevant, and compliant timekeeping policies and procedures which are maintained +- Maintain accurate and timely timesheets, for all CivicActions' Team Members, to support accurate and compliant invoicing to all CivicActions' customers +- All CivicActions' Team Members are trained upon hire with annual refresher trainings regarding accurate timekeeping practices and policies +- All CivicActions' Team Members are responsible for submitting accurate, compliant, and reasonable timesheets +- CivicActions' Project Managers and Managers must review all time / timesheets, for completeness, accuracy, and reasonableness +- Appropriate segregation of duties exists between those individuals who are responsible for administrative timekeeping management and the processing of payroll ### 3.2 Timekeeping requirements It is expected that all CivicActions' Team Members will comply and follow the referenced timekeeping requirements: -- All timekeeping entries have an audit trail to include the CivicActions' Team Member name, date, and time. Audit trail should exist at a minimum for the following: initial time entry, Team Member signature (which is completed through data entry by logged in Team Members), supervisory approval, evidence of corrections if applicable -- All time must be accurately recorded in a timely manner. This includes properly recording hours worked to applicable / appropriate final cost objectives (i.e., Direct or Indirect) -- All CivicActions' Team Members must account for and record all hours worked for every day worked -- All CivicActions' Team Members must input and save their hours for each day, no later than 10:00 am local time, the following business day being reported -- On the last business day of the pay period, CivicActions' Team Members must submit their timesheet, no later than 10:00 am local time, the following business day of the last day of the pay period -- Manager's must review and approve their CivicActions' Team Member timesheet(s), no later than 5:00 pm local time, the following business day of the last day of the pay period, once the CivicActions' Team Member has signed off on their timesheet -- All CivicActions' Team Members are responsible for entering and submitting their own timesheets. No other Team Member shall enter time for another CivicActions' Team Member, unless under special circumstances discussed in section _4.3 Timekeeping Special Circumstances_ -- The forward booking of time is strictly prohibited, except for when a Team Member is taking leave. If an Team Member is taking leave, they are allowed to enter time ahead of the time taken off -- Any Direct or Indirect labor which is considered unallowable, is recorded as such, to the appropriate unallowable project +- All timekeeping entries have an audit trail to include the CivicActions' Team Member name, date, and time. Audit trail should exist at a minimum for the following: initial time entry, Team Member signature (which is completed through data entry by logged in Team Members), supervisory approval, evidence of corrections if applicable +- All time must be accurately recorded in a timely manner. This includes properly recording hours worked to applicable / appropriate final cost objectives (i.e., Direct or Indirect) +- All CivicActions' Team Members must account for and record all hours worked for every day worked +- All CivicActions' Team Members must input and save their hours for each day, no later than 10:00 am local time, the following business day being reported +- On the last business day of the pay period, CivicActions' Team Members must submit their timesheet, no later than 10:00 am local time, the following business day of the last day of the pay period +- Manager's must review and approve their CivicActions' Team Member timesheet(s), no later than 5:00 pm local time, the following business day of the last day of the pay period, once the CivicActions' Team Member has signed off on their timesheet +- All CivicActions' Team Members are responsible for entering and submitting their own timesheets. No other Team Member shall enter time for another CivicActions' Team Member, unless under special circumstances discussed in section _4.3 Timekeeping Special Circumstances_ +- The forward booking of time is strictly prohibited, except for when a Team Member is taking leave. If an Team Member is taking leave, they are allowed to enter time ahead of the time taken off +- Any Direct or Indirect labor which is considered unallowable, is recorded as such, to the appropriate unallowable project ## 4 —Timekeeping @@ -159,31 +159,31 @@ Eligible Team Members are entitled to Holiday pay and associated Office Closing CivicActions conducts both onboarding and annual timekeeping training, which is required to be attended by all CivicActions' Team Members. Both trainings include: -- **Section One:** Government requirements for timekeeping and importance of accurate time charging in the Government space -- **Section Two:** Discuss and review the process for entering in time (i.e., how to physically enter in time to the Unanet system) -- **Section Three:** Overview of time charging key policy points / responsibility of all Team Members, which include, but not limited to: +- **Section One:** Government requirements for timekeeping and importance of accurate time charging in the Government space +- **Section Two:** Discuss and review the process for entering in time (i.e., how to physically enter in time to the Unanet system) +- **Section Three:** Overview of time charging key policy points / responsibility of all Team Members, which include, but not limited to: - - Defining what Direct and Indirect means - - Discuss types of activities considered to be Direct versus Indirect for labor - - Discuss importance of recording all hours worked (Direct / Indirect) - - Proper recording of hours to the applicable project charge code (Direct / Indirect) - - Requirements for entering time on a daily basis - - Importance of never forward booking time, with the exception of leave - - Discuss process for requesting access to a project charge codes Direct / Indirect (if applicable) - - Discuss what an Team Member should do in the event they are unable to record their time - - Discuss what an Team Member should do if they have a timesheet correction - - Discuss how to record Paid Time Off / Holiday / Leave + - Defining what Direct and Indirect means + - Discuss types of activities considered to be Direct versus Indirect for labor + - Discuss importance of recording all hours worked (Direct / Indirect) + - Proper recording of hours to the applicable project charge code (Direct / Indirect) + - Requirements for entering time on a daily basis + - Importance of never forward booking time, with the exception of leave + - Discuss process for requesting access to a project charge codes Direct / Indirect (if applicable) + - Discuss what an Team Member should do in the event they are unable to record their time + - Discuss what an Team Member should do if they have a timesheet correction + - Discuss how to record Paid Time Off / Holiday / Leave -- **Section Four:** Overview of Manager review roles / responsibilities +- **Section Four:** Overview of Manager review roles / responsibilities - - Complete, Accurate, Reasonable Review - - Review the process for Managers to physically review the timesheet + - Complete, Accurate, Reasonable Review + - Review the process for Managers to physically review the timesheet -- **Section Five:** Key takeaways and resources +- **Section Five:** Key takeaways and resources - - Review quick reference / how to guides readily available - - Provide Team Members a place where they can go with questions for time entry or review - - Provide Team Members a place to go, in the event that they suspect fraud + - Review quick reference / how to guides readily available + - Provide Team Members a place where they can go with questions for time entry or review + - Provide Team Members a place to go, in the event that they suspect fraud ### 4.6 Self audits diff --git a/company-policies/timesheets.md b/company-policies/timesheets.md index 28b85a5918..5727ece2d7 100644 --- a/company-policies/timesheets.md +++ b/company-policies/timesheets.md @@ -8,8 +8,8 @@ You are responsible for reporting your own time, on time. You will need to track You will need to track either: -- 8 hours for a full day -- 4 hours for a half day +- 8 hours for a full day +- 4 hours for a half day A full-time employee is expected to record a 40-hour work week in their timesheet. @@ -29,22 +29,22 @@ To create a timesheet: 1. Open the Unanet -- Dashboard. The dashboard has sections including: - - Active Timesheets - - Current Leave Requests - - Active Expense Reports - - If applicable, Approvals + - Active Timesheets + - Current Leave Requests + - Active Expense Reports + - If applicable, Approvals 2. On the top right-hand side of each section, locate the + Button (+ Timesheet, + Leave Request, + Expense). Select the applicable + Button to create a new timesheet. ## How to enter time -- Bill your time to the client in 15-minute increments. Unanet will automatically round in the reports, but you'll see actuals in your timesheet. +- Bill your time to the client in 15-minute increments. Unanet will automatically round in the reports, but you'll see actuals in your timesheet. -- If a task took 2 minutes to complete but another task for the same project took 10, consider lumping them together to 15 minutes. +- If a task took 2 minutes to complete but another task for the same project took 10, consider lumping them together to 15 minutes. -- Log your time in Unanet accurately. If you spend 6 hours on a project and 2 hours on internal work, ensure the time is logged correctly in each of the Unanet entries. +- Log your time in Unanet accurately. If you spend 6 hours on a project and 2 hours on internal work, ensure the time is logged correctly in each of the Unanet entries. -- If you need to split time between charge codes, 0.25 is acceptable. All time entry is to the nearest quarter (0.25). +- If you need to split time between charge codes, 0.25 is acceptable. All time entry is to the nearest quarter (0.25). Many team members at CivicActions are disciplined in keeping track of their hours, or are able to work in structured blocks that allow them to easily record their time at the end of each day. If you are unsure, you can [check your Gmail](https://mail.google.com/mail/u/0/#sent), [review your Google Drive](https://drive.google.com/drive/u/0/recent), [check Zoom meetings](https://zoom.us/meeting#/previous), search Slack messages (example: on:Monday from:me), or look at the GitHub overview when you log in. @@ -58,8 +58,8 @@ Once you have completed your timesheet for the day, you must save it. Select the Once you have completed entering in all time for the applicable reporting period, you must submit your timesheet to your manager. -- Select the blue Submit button at the bottom of the page. -- You will then be asked to confirm again, by selecting the Submit button on the next screen. +- Select the blue Submit button at the bottom of the page. +- You will then be asked to confirm again, by selecting the Submit button on the next screen. ### Each pay period @@ -69,20 +69,20 @@ By the following business day of the last day of the pay period, you must submit You are responsible for making all timesheet corrections prior to the timesheet period being closed. Timesheet corrections: -- Should be in limited circumstances -- Must be handled within Unanet +- Should be in limited circumstances +- Must be handled within Unanet For current period adjustments: -- Make the necessary correction(s) within the applicable timesheet -- Include an explanation as to why the correction(s) is needed -- Your manager will review and approve the corrected timesheet +- Make the necessary correction(s) within the applicable timesheet +- Include an explanation as to why the correction(s) is needed +- Your manager will review and approve the corrected timesheet For prior period adjustments: -- You must coordinate the corrections with your project manager and/or manager. -- The Resource Planning Analyst makes the necessary corrective adjustment and adds an explanation as to why the correction is needed. -- You and your manager will review the corrected timesheet for accuracy. +- You must coordinate the corrections with your project manager and/or manager. +- The Resource Planning Analyst makes the necessary corrective adjustment and adds an explanation as to why the correction is needed. +- You and your manager will review the corrected timesheet for accuracy. ## Manager approvals  @@ -101,13 +101,13 @@ To approve your team member's timesheet: 3. Click on the magnifying glass to the left of your team member's name to view their timesheet. 4. Review three general items: - - Completeness - - Accuracy - - Reasonableness + - Completeness + - Accuracy + - Reasonableness 5. If the team member's timesheet is complete, accurate, and reasonable, and the project, CLIN / Task and labor category and bill rate (if applicable) are correct, then you can approve the timesheet. You will be asked to approve the timesheet again, on the next screen. - - If the timesheet is incomplete, inaccurate, unreasonable, or has an incorrect labor category or CLIN / task, you must disapprove the timesheet. You must provide the team member with a reason as to why the timesheet was disapproved. + - If the timesheet is incomplete, inaccurate, unreasonable, or has an incorrect labor category or CLIN / task, you must disapprove the timesheet. You must provide the team member with a reason as to why the timesheet was disapproved. If you are out on leave during a timesheet processing day, you should notify the assigned Alternate Approver in advance, to ensure timesheet approvals are completed on time. @@ -115,11 +115,11 @@ If you are out on leave during a timesheet processing day, you should notify the To get help with timesheets, project codes, and using Unanet: -- Join #unanet in Slack and ping @unanet_support -- View pinned items in the #unanet slack channel -- Search the [Unanet knowledge center from the support center (requires account)](https://support.unanet.com/) -- [Instructions](https://docs.google.com/presentation/d/1IEl3c8pOAYz5KNM4tVDemjvx5O-5m5WF21r4saANsFw/edit#slide=id.gce3d6a447a_0_89) (deck) -- [Time Off policy (US)](../employee-benefits/README.md) -- [Time Off policy (Canada)](../employee-benefits/canada-benefits-policy.md) -- [Timekeeping policy](https://drive.google.com/file/d/1m18Ellyi_llWCPI6dm4FoNKqBXIoV18b/view?usp=sharing) -- [Timekeeping FAQs](https://drive.google.com/file/d/1_liB4o8iQ93qLATThnxpjfyXmvyguHFQ/view?usp=sharing) +- Join #unanet in Slack and ping @unanet_support +- View pinned items in the #unanet slack channel +- Search the [Unanet knowledge center from the support center (requires account)](https://support.unanet.com/) +- [Instructions](https://docs.google.com/presentation/d/1IEl3c8pOAYz5KNM4tVDemjvx5O-5m5WF21r4saANsFw/edit#slide=id.gce3d6a447a_0_89) (deck) +- [Time Off policy (US)](../employee-benefits/README.md) +- [Time Off policy (Canada)](../employee-benefits/canada-benefits-policy.md) +- [Timekeeping policy](https://drive.google.com/file/d/1m18Ellyi_llWCPI6dm4FoNKqBXIoV18b/view?usp=sharing) +- [Timekeeping FAQs](https://drive.google.com/file/d/1_liB4o8iQ93qLATThnxpjfyXmvyguHFQ/view?usp=sharing) diff --git a/employee-benefits/README.md b/employee-benefits/README.md index 97e6b635d6..1ea2ef64ff 100644 --- a/employee-benefits/README.md +++ b/employee-benefits/README.md @@ -51,10 +51,10 @@ Employees should follow the following procedure for providing notice of, schedul **Sample messages to demonstrate how to request timeoff in Unanet:** -- _Hello, I am out sick today. I've let my team know via slack not to expect me today._ -- _Hello, I want to take Aug 1-7 off. I have coordinated coverage with my team and remind them again prior to my time off._ -- _Hello, I am doing a prodev workshop on Feb 1. I have notified my team that I will be out that day._ -- _Hello, I need tomorrow off for a last minute doctor appointment. I have notified those who need to know not to expect me tomorrow._ +- _Hello, I am out sick today. I've let my team know via slack not to expect me today._ +- _Hello, I want to take Aug 1-7 off. I have coordinated coverage with my team and remind them again prior to my time off._ +- _Hello, I am doing a prodev workshop on Feb 1. I have notified my team that I will be out that day._ +- _Hello, I need tomorrow off for a last minute doctor appointment. I have notified those who need to know not to expect me tomorrow._ ## Exempt employees -- time off @@ -80,16 +80,16 @@ Unused PTO is not eligible for payout at the end of a calendar year. Unless cont Eligible employees may use paid time off under this policy beginning on their 90th day of employment. It can be used for traditional vacation purposes, personal time, or sick time, including sick time under any applicable paid sick leave law. This includes to: -- attend appointments or receive care for the employee's own physical or mental illness, injury, or medical condition, including conditions requiring home care, professional medical diagnosis or treatment, or preventive care; or -- attend appointments or provide care for an eligible family member's physical or mental illness, injury, or medical condition, including conditions requiring home care, professional medical diagnosis or care, or preventive care; or -- address the psychological, physical, or legal effects of domestic violence, harassment, sexual assault, or stalking involving an employee or an eligible family member, or where applicable, a "household member" (including stepparents and stepchildren, grandchildren, current and former spouses and domestic partners, persons who have a child in common, adult persons related by blood or marriage, adult persons who have resided or are residing together, and persons 16 years of age or older who are or were residing together and who are or were in a dating relationship); or -- take time off when an employee's place of business or a child's school or place of care has been closed by order of a public official due to a public health emergency or for other health-related reasons; or -- for absences from work when an employee or an eligible family member has been the victim of a family offense matter, sexual offense, stalking, or human trafficking; or -- take time off when an employee or an eligible family member is quarantined by a public health authority or health care provider; or -- take time off to attend a funeral, make arrangements for, or grieve following the death of an eligible family member, within 60 days of death; or -- bond with a newborn, newly adopted or placed foster child under age 18 , or an adopted or foster child over age 18 if incapable of self-care because of a mental or physical disability, if completed within 12 months of birth or placement; or -- take time off for bone marrow or organ donation by the employee or an eligible family member; or -- take time off in connection with an employee's child to attend a school-related conference, meeting, or other event requested or required by a school administrator, teacher, or other professional staff member responsible for the child's education, or to attend a meeting regarding care provided to the child in connection with the child's health conditions or disability. +- attend appointments or receive care for the employee's own physical or mental illness, injury, or medical condition, including conditions requiring home care, professional medical diagnosis or treatment, or preventive care; or +- attend appointments or provide care for an eligible family member's physical or mental illness, injury, or medical condition, including conditions requiring home care, professional medical diagnosis or care, or preventive care; or +- address the psychological, physical, or legal effects of domestic violence, harassment, sexual assault, or stalking involving an employee or an eligible family member, or where applicable, a "household member" (including stepparents and stepchildren, grandchildren, current and former spouses and domestic partners, persons who have a child in common, adult persons related by blood or marriage, adult persons who have resided or are residing together, and persons 16 years of age or older who are or were residing together and who are or were in a dating relationship); or +- take time off when an employee's place of business or a child's school or place of care has been closed by order of a public official due to a public health emergency or for other health-related reasons; or +- for absences from work when an employee or an eligible family member has been the victim of a family offense matter, sexual offense, stalking, or human trafficking; or +- take time off when an employee or an eligible family member is quarantined by a public health authority or health care provider; or +- take time off to attend a funeral, make arrangements for, or grieve following the death of an eligible family member, within 60 days of death; or +- bond with a newborn, newly adopted or placed foster child under age 18 , or an adopted or foster child over age 18 if incapable of self-care because of a mental or physical disability, if completed within 12 months of birth or placement; or +- take time off for bone marrow or organ donation by the employee or an eligible family member; or +- take time off in connection with an employee's child to attend a school-related conference, meeting, or other event requested or required by a school administrator, teacher, or other professional staff member responsible for the child's education, or to attend a meeting regarding care provided to the child in connection with the child's health conditions or disability. ## Written documentation of time off @@ -122,13 +122,13 @@ To the extent state or local laws mandate paid sick leave, this policy is intend For purposes of this paid time off policy, and where consistent with applicable law: -- **"Children"** shall include biological, adopted, and foster children, stepchildren, or legal wards of an employee or an employee's spouse, or children for whom an employee or an employee's spouse stands "in loco parentis" or to whom the employee stood "in loco parentis" when the individual was a minor. -- **"Eligible family member"** shall include an employee's: (1) spouse, (2) children, (3) parents, (4) grandparents, (5) grandchildren, (6) siblings, and, in limited jurisdictions (7) any individual related by blood or affinity whose close association with the employee is the equivalent of a family relationship. -- **"Family offense matter"** shall include an act or threat of an act that may constitute disorderly conduct, harassment, aggravated harassment, sexual misconduct, forcible touching, sexual abuse, stalking, criminal mischief, menacing, reckless endangerment, strangulation, criminal obstruction of breathing or blood circulation, assault, attempted assault, identity theft, grand larceny, coercion under applicable law between spouses or former spouses, or between parent and child or between members of the same family or household. -- **"Grandparents"** and **"grandchildren"** include biological, adopted, foster, and step-relationships of the employee or the employee's spouse. -- **"Parents"** shall include biological, adopted, and foster parents or stepparents of an employee or an employee's spouse, or a legal guardian or person who stood "in loco parentis" to an employee or an employee's spouse as a minor child. -- **"Siblings"** shall include biological, adopted, and foster siblings, step-siblings, half-siblings, and their spouses. -- **"Spouse"** shall include domestic partners, registered domestic partners, civil union partners, life partners, or a designated person of the employee's choice. +- **"Children"** shall include biological, adopted, and foster children, stepchildren, or legal wards of an employee or an employee's spouse, or children for whom an employee or an employee's spouse stands "in loco parentis" or to whom the employee stood "in loco parentis" when the individual was a minor. +- **"Eligible family member"** shall include an employee's: (1) spouse, (2) children, (3) parents, (4) grandparents, (5) grandchildren, (6) siblings, and, in limited jurisdictions (7) any individual related by blood or affinity whose close association with the employee is the equivalent of a family relationship. +- **"Family offense matter"** shall include an act or threat of an act that may constitute disorderly conduct, harassment, aggravated harassment, sexual misconduct, forcible touching, sexual abuse, stalking, criminal mischief, menacing, reckless endangerment, strangulation, criminal obstruction of breathing or blood circulation, assault, attempted assault, identity theft, grand larceny, coercion under applicable law between spouses or former spouses, or between parent and child or between members of the same family or household. +- **"Grandparents"** and **"grandchildren"** include biological, adopted, foster, and step-relationships of the employee or the employee's spouse. +- **"Parents"** shall include biological, adopted, and foster parents or stepparents of an employee or an employee's spouse, or a legal guardian or person who stood "in loco parentis" to an employee or an employee's spouse as a minor child. +- **"Siblings"** shall include biological, adopted, and foster siblings, step-siblings, half-siblings, and their spouses. +- **"Spouse"** shall include domestic partners, registered domestic partners, civil union partners, life partners, or a designated person of the employee's choice. Eligible employees should contact the PeopleOps Team with questions concerning whether any of the above definitions apply in a particular jurisdiction. @@ -157,7 +157,7 @@ When you have a technical issue with your home network, power and personal equip ### Slack channels -- You can go to the following Slack channels for support: #windows #osx #gnu-linux +- You can go to the following Slack channels for support: #windows #osx #gnu-linux ## Personal Leave of Absence diff --git a/employee-benefits/canada-benefits-policy.md b/employee-benefits/canada-benefits-policy.md index ff9ce2e004..f188ab420e 100644 --- a/employee-benefits/canada-benefits-policy.md +++ b/employee-benefits/canada-benefits-policy.md @@ -51,10 +51,10 @@ Employees should follow the following procedure for providing notice of, schedul **Sample messages to demonstrate how to request timeoff in Unanet:** -- _Hello, I am out sick today. I've let my team know via slack not to expect me today._ -- _Hello, I want to take Aug 1-7 off. I have coordinated coverage with my team and remind them again prior to my time off._ -- _Hello, I am doing a prodev workshop on Feb 1. I have notified my team that I will be out that day._ -- _Hello, I need tomorrow off for a last minute doctor appointment. I have notified those who need to know not to expect me tomorrow._ +- _Hello, I am out sick today. I've let my team know via slack not to expect me today._ +- _Hello, I want to take Aug 1-7 off. I have coordinated coverage with my team and remind them again prior to my time off._ +- _Hello, I am doing a prodev workshop on Feb 1. I have notified my team that I will be out that day._ +- _Hello, I need tomorrow off for a last minute doctor appointment. I have notified those who need to know not to expect me tomorrow._ ## Scheduling shifts @@ -81,7 +81,7 @@ When you have a technical issue with your home network, power and personal equip ### Slack channels -- You can go to the following Slack channels for support: #windows #osx #gnu-linux +- You can go to the following Slack channels for support: #windows #osx #gnu-linux ## Personal Leave of Absence diff --git a/employee-benefits/canada-tech-stipend.md b/employee-benefits/canada-tech-stipend.md index 55fe4da6c9..a601294b9f 100644 --- a/employee-benefits/canada-tech-stipend.md +++ b/employee-benefits/canada-tech-stipend.md @@ -9,13 +9,13 @@ As part of CivicActions commitment to work/life balance and our movement toward ## Definitions -- "Eligible Team Member" means direct employees of CivicActions Digital Services, ULC. Individuals who are independent contractors, work for staffing firms, or who are employed by other companies that contract with CivicActions are not eligible. -- "Annual Eligibility Date" means: +- "Eligible Team Member" means direct employees of CivicActions Digital Services, ULC. Individuals who are independent contractors, work for staffing firms, or who are employed by other companies that contract with CivicActions are not eligible. +- "Annual Eligibility Date" means: 1. The Annual Eligibility Date for Eligible Team Members who have been with CivicActions for more than one year since their last hire date is the annual anniversary of their last hire date. 1. The Annual Eligibility Date for Team Members who are hired by CivicActions after April 1, 2021 and have been with CivicActions for less then a year is the last day of the ninety-day Introductory Period. -- The "Payment Amount" as of January 1, 2024 is $1,103 CAD for team members who are issued managed devices (excluding project specific devices) and $1,618 CAD for team members who bring their own device. The amount will be reviewed annually. +- The "Payment Amount" as of January 1, 2024 is $1,103 CAD for team members who are issued managed devices (excluding project specific devices) and $1,618 CAD for team members who bring their own device. The amount will be reviewed annually. ## Policy diff --git a/employee-benefits/on-call-stipend.md b/employee-benefits/on-call-stipend.md index 96c1a30f59..6735c4aafb 100644 --- a/employee-benefits/on-call-stipend.md +++ b/employee-benefits/on-call-stipend.md @@ -15,34 +15,34 @@ CivicActions recognizes that being on-call outside of normal business hours take ## Eligibility -- Only team members who are salaried exempt employees in non-Operational Support roles are eligible for On-call stipends Typically this includes roles that are non-operations focused roles such as software engineering, project management, product management, UX, helpdesk support, and other roles that do not include on-call support as an ordinary job requirement. -- Team members whose work that ordinarily includes operational support or whose position description includes 24x7 support as a responsibility are not eligible for the stipend. CivicActions considers on-call duty support as an ordinary responsibility for Operational Support Roles. CivicActions accounts for this responsibility in setting compensation for those roles. -- Stipends are only provided when a client project requires ongoing 24x7 support for one or more systems. -- Stipends will only be offered to eligible employees who are required to participate in a 24x7 support schedule for at least 30 continuous calendar days. +- Only team members who are salaried exempt employees in non-Operational Support roles are eligible for On-call stipends Typically this includes roles that are non-operations focused roles such as software engineering, project management, product management, UX, helpdesk support, and other roles that do not include on-call support as an ordinary job requirement. +- Team members whose work that ordinarily includes operational support or whose position description includes 24x7 support as a responsibility are not eligible for the stipend. CivicActions considers on-call duty support as an ordinary responsibility for Operational Support Roles. CivicActions accounts for this responsibility in setting compensation for those roles. +- Stipends are only provided when a client project requires ongoing 24x7 support for one or more systems. +- Stipends will only be offered to eligible employees who are required to participate in a 24x7 support schedule for at least 30 continuous calendar days. ## Responsibilities -- _Response Procedures_. Team members participating in on-call are expected to follow the project incident response plan (IRP), or [CivicActions IRP](../common-practices-tools/security/incident-response-plan.md) if the project does not yet have one. -- _Receiving Alerts._ Team members are responsible for configuring and testing their phone to ensure they receive and notice alerts when they are on-call in accordance with the applicable IRP. You should check with your PM and on-call team documentation to determine the specific mobile app and configuration required to receive alerts and bypass quiet or do-not-disturb mode. -- _Support Coverage._ Team members are responsible for being aware of when they are on-call and proactively finding support coverage in advance for any periods where they will be unable to respond to an alert, as well as helping cover other team members when they are able. -- _Response time._ The IRP or Service Level Agreement/Objective for each project shall dictate the required response time. If the IRP plan does not specific the required response period employees are expected to be available to respond within 2 hours. -- _Limitation on Activities._ Team members are responsible for being available to respond in the required response time in a professional and effective manner. This may mean limiting travel, participation in recreational activities or the use of drugs or alcohol during your scheduled on-call period. -- Remember that responding to an alert is part of your work week, not an addition - if you spend time responding to an out of work hours incident please feel encouraged to take time off the next day to regain your balance. +- _Response Procedures_. Team members participating in on-call are expected to follow the project incident response plan (IRP), or [CivicActions IRP](../common-practices-tools/security/incident-response-plan.md) if the project does not yet have one. +- _Receiving Alerts._ Team members are responsible for configuring and testing their phone to ensure they receive and notice alerts when they are on-call in accordance with the applicable IRP. You should check with your PM and on-call team documentation to determine the specific mobile app and configuration required to receive alerts and bypass quiet or do-not-disturb mode. +- _Support Coverage._ Team members are responsible for being aware of when they are on-call and proactively finding support coverage in advance for any periods where they will be unable to respond to an alert, as well as helping cover other team members when they are able. +- _Response time._ The IRP or Service Level Agreement/Objective for each project shall dictate the required response time. If the IRP plan does not specific the required response period employees are expected to be available to respond within 2 hours. +- _Limitation on Activities._ Team members are responsible for being available to respond in the required response time in a professional and effective manner. This may mean limiting travel, participation in recreational activities or the use of drugs or alcohol during your scheduled on-call period. +- Remember that responding to an alert is part of your work week, not an addition - if you spend time responding to an out of work hours incident please feel encouraged to take time off the next day to regain your balance. ## Payment -- The on-call stipend amount is $2000 per fiscal quarter (effective starting July, 1, 2020). -- This amount is prorated by day for people joining/leaving the on-call rotation mid-quarter. -- This amount is prorated for part-time employees. -- The stipend is paid quarterly after the conclusion of the fiscal quarter. -- Team members on multiple on-call rotations are only eligible for a single stipend. -- The frequency of actually being on-call (i.e. size of on-call team) does not affect the stipend. -- Nothing in this policy limits team members, including non-exempt employees, rights to overtime compensation for those employees who are entitled to overtime by law. +- The on-call stipend amount is $2000 per fiscal quarter (effective starting July, 1, 2020). +- This amount is prorated by day for people joining/leaving the on-call rotation mid-quarter. +- This amount is prorated for part-time employees. +- The stipend is paid quarterly after the conclusion of the fiscal quarter. +- Team members on multiple on-call rotations are only eligible for a single stipend. +- The frequency of actually being on-call (i.e. size of on-call team) does not affect the stipend. +- Nothing in this policy limits team members, including non-exempt employees, rights to overtime compensation for those employees who are entitled to overtime by law. ## Process and administration -- Ordinarily the CivicActions Project Manager on the project will ask for volunteers from qualified team members when a need for team members to participate in on-call rotation occurs. (In the event that no qualified and eligible employees volunteer, CivicActions may assign individuals to participate to meet the project requirements.) -- Employees are ordinarily only required to participate in on-call duty when required by the project requirements. -- Project Managers are responsible for: - - Notifying team members of changes to their participation in the on-call rotation schedule in writing; and - - Keeping updated the [On-call tracking Spreadsheet](https://docs.google.com/spreadsheets/d/11jAuW7K08V5m4wyRNkddC2f_AsAtFrTXDbpUdXu272E/edit#gid=0). +- Ordinarily the CivicActions Project Manager on the project will ask for volunteers from qualified team members when a need for team members to participate in on-call rotation occurs. (In the event that no qualified and eligible employees volunteer, CivicActions may assign individuals to participate to meet the project requirements.) +- Employees are ordinarily only required to participate in on-call duty when required by the project requirements. +- Project Managers are responsible for: + - Notifying team members of changes to their participation in the on-call rotation schedule in writing; and + - Keeping updated the [On-call tracking Spreadsheet](https://docs.google.com/spreadsheets/d/11jAuW7K08V5m4wyRNkddC2f_AsAtFrTXDbpUdXu272E/edit#gid=0). diff --git a/employee-benefits/professional-development.md b/employee-benefits/professional-development.md index c3caa97939..ee0551061d 100644 --- a/employee-benefits/professional-development.md +++ b/employee-benefits/professional-development.md @@ -6,12 +6,12 @@ title: Professional development CivicActions recognizes the importance of individual professional development for all team members. We value professional development for a number of reasons: -- It's a win-win. Professional development grows the depth and value of the company offerings and enhances your career opportunities too. -- Professional development provides career mobility for each person - increasing our feeling of safety, which leads to: - - Having the courage to fail, which leads to experimentation, innovation, and learning - - Having the courage to challenge the status quo, which leads to organizational learning - - Having the courage to be vulnerable, which leads to authentic communications and connection - - Open-minded thinking, which leads to increased tolerance of others ideas and personality styles +- It's a win-win. Professional development grows the depth and value of the company offerings and enhances your career opportunities too. +- Professional development provides career mobility for each person - increasing our feeling of safety, which leads to: + - Having the courage to fail, which leads to experimentation, innovation, and learning + - Having the courage to challenge the status quo, which leads to organizational learning + - Having the courage to be vulnerable, which leads to authentic communications and connection + - Open-minded thinking, which leads to increased tolerance of others ideas and personality styles **CivicActions supports and encourages the Professional Development (prodev) of each team member by providing an annual budget of $1,200 per person to be used for prodev-related expenses.** Note: If you are a part-time employee or under 30 hours/week, your budget will be prorated based on your working hours. @@ -40,12 +40,12 @@ Each full-time team member is provided an annual prodev budget of $1,200. If you This budget can be used a number of things: -- Materials used to obtain professional certifications including classes, study guides, books -- Testing fees and renewal costs associated with professional certifications -- Books -- Online courses -- [Travel and accommodation for attending conferences](../company-policies/travel-time-tracking-and-expenses.md) -- Other costs incurred from you becoming a smarter, more awesomer version of you +- Materials used to obtain professional certifications including classes, study guides, books +- Testing fees and renewal costs associated with professional certifications +- Books +- Online courses +- [Travel and accommodation for attending conferences](../company-policies/travel-time-tracking-and-expenses.md) +- Other costs incurred from you becoming a smarter, more awesomer version of you There are some limitations on the prodev budget usage. Hardware purchases are not covered under the prodev stipend. For spending amounts over $50, you'll need to get [approval in advance](../company-policies/expenses.md). Anything under $50 can be purchased without permission as long as it supports professional development goals. Receipts and expense sheets should be submitted in the usual way through Unanet, under the "CivicActions -> Professional development" project. diff --git a/employee-benefits/us-tech-stipend.md b/employee-benefits/us-tech-stipend.md index 5b219c63f1..2cf4f06962 100644 --- a/employee-benefits/us-tech-stipend.md +++ b/employee-benefits/us-tech-stipend.md @@ -9,13 +9,13 @@ As part of CivicActions commitment to work/life balance and our movement toward ## Definitions -- "Eligible Team Member" means direct employees of CivicActions, Inc, including CivicActions, Inc worksite employees of TriNet, Inc. Individuals who are independent contractors, work for staffing firms, or who are employed by other companies that contract with CivicActions are not eligible. -- "Annual Eligibility Date" means: +- "Eligible Team Member" means direct employees of CivicActions, Inc, including CivicActions, Inc worksite employees of TriNet, Inc. Individuals who are independent contractors, work for staffing firms, or who are employed by other companies that contract with CivicActions are not eligible. +- "Annual Eligibility Date" means: 1. The Annual Eligibility Date for Eligible Team Members who have been with CivicActions for more than one year since their last hire date is the annual anniversary of their last hire date. 1. The Annual Eligibility Date for Team Members who are hired by CivicActions after April 1, 2021 and have been with CivicActions for less then a year is the last day of the ninety-day Introductory Period. -- The "Payment Amount" as of January 1, 2024 is $816 USD for team members who are issued managed devices (excluding project specific devices) and $1,197 USD for team members who bring their own device. The amount will be reviewed annually. +- The "Payment Amount" as of January 1, 2024 is $816 USD for team members who are issued managed devices (excluding project specific devices) and $1,197 USD for team members who bring their own device. The amount will be reviewed annually. ## Policy diff --git a/practice-areas/README.md b/practice-areas/README.md index 14cf1666a6..6289308bd0 100644 --- a/practice-areas/README.md +++ b/practice-areas/README.md @@ -6,18 +6,18 @@ title: About practice areas Practice areas are self-organized groups oriented around a specific practice or craft. They help: -- provide client services -- build the team that delivers those services -- work across departments and delivery to develop, market, sell, deliver and grow a set of related services -- foster learning, continuous improvement and cross-pollination of ideas and best practice across the company +- provide client services +- build the team that delivers those services +- work across departments and delivery to develop, market, sell, deliver and grow a set of related services +- foster learning, continuous improvement and cross-pollination of ideas and best practice across the company It is important to note practice areas may overlap in places, and that client projects can often be served by more than one practice area during the course of delivery. Similarly team members may work across multiple practice areas, even in a single day. Each client-facing practice area: -- is identified by a unique 2 character code; this is used to identify practice area work in Unanet and other tools -- has one or two Practice Area leads. The lead is responsible for guiding the collaborative creation of vision, strategy and goals of the practice area, supporting departments and people planning. -- has a Slack channel, with key materials such as Trello boards, strategic planning documents, roadmaps, etc pinned in the channel +- is identified by a unique 2 character code; this is used to identify practice area work in Unanet and other tools +- has one or two Practice Area leads. The lead is responsible for guiding the collaborative creation of vision, strategy and goals of the practice area, supporting departments and people planning. +- has a Slack channel, with key materials such as Trello boards, strategic planning documents, roadmaps, etc pinned in the channel Practice area meetings should be added to the main "CivicActions" calendar for visibility - see the calendar for the latest schedule and feel free to copy the event to your calendar if you would like. diff --git a/practice-areas/accessibility/README.md b/practice-areas/accessibility/README.md index b18973391a..93593d9a9d 100644 --- a/practice-areas/accessibility/README.md +++ b/practice-areas/accessibility/README.md @@ -14,28 +14,28 @@ If you aren't part of the CivicActions team [let us know](https://accessibility. ## Join us -- Join the #accessibility CivicActions Slack channel (CivicActions Internal) +- Join the #accessibility CivicActions Slack channel (CivicActions Internal) -- [Join the meetings](https://accessibility.civicactions.com/calendar) (check-ins + prioritization + practice area calls (CivicActions Internal) +- [Join the meetings](https://accessibility.civicactions.com/calendar) (check-ins + prioritization + practice area calls (CivicActions Internal) -- Ask a question in Slack or in our [GitHub Discussion](https://github.com/CivicActions/accessibility/discussions) page +- Ask a question in Slack or in our [GitHub Discussion](https://github.com/CivicActions/accessibility/discussions) page -- Provide a [GitHub Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) or create an issue if you see a correction or additional resource that should be included. +- Provide a [GitHub Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) or create an issue if you see a correction or additional resource that should be included. -- Become an [Accessibility Champion](https://accessibility.civicactions.com/guide/champions-program) (CivicActions Internal) +- Become an [Accessibility Champion](https://accessibility.civicactions.com/guide/champions-program) (CivicActions Internal) ## CivicActions accessibility resources -- Website: [https://accessibility.civicactions.com/](https://accessibility.civicactions.com/) +- Website: [https://accessibility.civicactions.com/](https://accessibility.civicactions.com/) -- Playbook: [https://accessibility.civicactions.com/playbook/](https://accessibility.civicactions.com/playbook/) +- Playbook: [https://accessibility.civicactions.com/playbook/](https://accessibility.civicactions.com/playbook/) -- Accessibility Guide: [https://accessibility.civicactions.com/guide/](https://accessibility.civicactions.com/guide/) +- Accessibility Guide: [https://accessibility.civicactions.com/guide/](https://accessibility.civicactions.com/guide/) -- HEART: [https://accessibility.civicactions.com/heart](https://accessibility.civicactions.com/heart) +- HEART: [https://accessibility.civicactions.com/heart](https://accessibility.civicactions.com/heart) -- Calendar: [https://accessibility.civicactions.com/calendar](https://accessibility.civicactions.com/calendar) +- Calendar: [https://accessibility.civicactions.com/calendar](https://accessibility.civicactions.com/calendar) -- Project Board: [https://github.com/CivicActions/accessibility/projects/1](https://github.com/CivicActions/accessibility/projects/1) +- Project Board: [https://github.com/CivicActions/accessibility/projects/1](https://github.com/CivicActions/accessibility/projects/1) -- Launching a community of practice: [https://medium.com/civicactions/launching-a-community-of-practice-for-accessibility-in-government-services-b0b085cd90d6](https://medium.com/civicactions/launching-a-community-of-practice-for-accessibility-in-government-services-b0b085cd90d6) +- Launching a community of practice: [https://medium.com/civicactions/launching-a-community-of-practice-for-accessibility-in-government-services-b0b085cd90d6](https://medium.com/civicactions/launching-a-community-of-practice-for-accessibility-in-government-services-b0b085cd90d6) diff --git a/practice-areas/design-and-research/README.md b/practice-areas/design-and-research/README.md index 3e17c47051..f5b19f48ad 100644 --- a/practice-areas/design-and-research/README.md +++ b/practice-areas/design-and-research/README.md @@ -36,29 +36,29 @@ We most often are contracted for government projects under the following broad d ### We start with discovery, not solutions -- We begin by listening -- We make every effort to design proactively, not reactively -- We believe in incremental experimentation through iteration -- We explore solutions through research, best practices, and equitable, accessible design approaches +- We begin by listening +- We make every effort to design proactively, not reactively +- We believe in incremental experimentation through iteration +- We explore solutions through research, best practices, and equitable, accessible design approaches ### We approach our work with authentic empathy -- We acknowledge each other's whole self -- We can show care for others when we show care for ourselves -- We acknowledge that we all work in different ways and we respect diversity in thought, approach, and execution +- We acknowledge each other's whole self +- We can show care for others when we show care for ourselves +- We acknowledge that we all work in different ways and we respect diversity in thought, approach, and execution ### Good enough should not be our default -- We strive to fix what is broken -- We advocate for, and educate others, on design best practices -- We seek to find solutions for all of humanity, not just a subset of users -- We have a growth mindset that is open to constructive feedback +- We strive to fix what is broken +- We advocate for, and educate others, on design best practices +- We seek to find solutions for all of humanity, not just a subset of users +- We have a growth mindset that is open to constructive feedback ### We achieve through imagination and iteration -- We push ourselves and each other to go beyond what we think we're capable of -- We know that success requires collaboration and teamwork -- We use metrics to gauge impact and guide decisions +- We push ourselves and each other to go beyond what we think we're capable of +- We know that success requires collaboration and teamwork +- We use metrics to gauge impact and guide decisions ## All creatives calls @@ -73,30 +73,30 @@ Our design team spends most of our time on billable projects, but we recognize t We've included some possible professional development resources below. You have $1200 per year (after your 90-day intro period) to spend on [professional development](../../employee-benefits/professional-development.md). Professional development conferences, courses, and webinars that align with your current or growth-level path can contribute to your yearly utilization targets, but you don't have to use your professional development for our practice area only. -- [Nielsen-Norman Group courses](https://www.nngroup.com/training/) -- [Innovate(us)](https://course.innovate-us.org/) -- [Config conference](https://config.figma.com/) -- [Leaders of Awesomeness community](https://leaders.centercentre.com/) -- [Centercentre previous workshops](https://essentials.centercentre.com/) +- [Nielsen-Norman Group courses](https://www.nngroup.com/training/) +- [Innovate(us)](https://course.innovate-us.org/) +- [Config conference](https://config.figma.com/) +- [Leaders of Awesomeness community](https://leaders.centercentre.com/) +- [Centercentre previous workshops](https://essentials.centercentre.com/) ## Tools A member of the design team can help you get access to the design tools we use at CivicActions and your project teams will get you project team access. -- [Figma](https://www.figma.com/) -- [Sketch](https://www.sketch.com/) -- [Screaming frog](https://www.screamingfrog.co.uk/) -- [Optimal Workshop](https://www.optimalworkshop.com/) -- [Airtable](https://airtable.com/) +- [Figma](https://www.figma.com/) +- [Sketch](https://www.sketch.com/) +- [Screaming frog](https://www.screamingfrog.co.uk/) +- [Optimal Workshop](https://www.optimalworkshop.com/) +- [Airtable](https://airtable.com/) ## Have a design request? One important use of the **#design** slack channel is for other practice areas to reach out to the CivicActions designers to ask for specific design requests. When asking for help, please include: -- The context for the request, including the target audience -- Your preferred delivery format (document, design, user flow, graphics, illustration, etc) -- A description or visualization of the solution/suggestion -- A timeline that includes enough lead time to iterate on the design before the deadline -- The point of contact for the request and describe any timeline requirements +- The context for the request, including the target audience +- Your preferred delivery format (document, design, user flow, graphics, illustration, etc) +- A description or visualization of the solution/suggestion +- A timeline that includes enough lead time to iterate on the design before the deadline +- The point of contact for the request and describe any timeline requirements While we address all requests as soon as they come in, ensuring each request has the above information ensures a faster response time and an easier project start. diff --git a/practice-areas/engineering/accessibility.md b/practice-areas/engineering/accessibility.md index 34d96721bf..72bd817bea 100644 --- a/practice-areas/engineering/accessibility.md +++ b/practice-areas/engineering/accessibility.md @@ -8,31 +8,31 @@ We implement Section 508 compliant sites and strive to meet the latest Web Conte ## How we do this -- We use base themes which strive to meet the W3C's WCAG 2.1 AA Success Criteria or above. -- We implement good SEO structures (which are generally good for accessibility). -- We implement responsive design strategies that can present complex data in hierarchical structures, capable of being navigated by audio cues. -- We believe that users should be able to personalize how content is presented. We strive to allow users to change color schemes and text size displays allow them to have a better user experience. -- We test sites using a combination of automated and manual testing. We leverage automated testing in the browser, with site-wide scans and also through integration in our CI/CD pipeline. -- We follow the best practices of the Drupal community, which includes accessibility. +- We use base themes which strive to meet the W3C's WCAG 2.1 AA Success Criteria or above. +- We implement good SEO structures (which are generally good for accessibility). +- We implement responsive design strategies that can present complex data in hierarchical structures, capable of being navigated by audio cues. +- We believe that users should be able to personalize how content is presented. We strive to allow users to change color schemes and text size displays allow them to have a better user experience. +- We test sites using a combination of automated and manual testing. We leverage automated testing in the browser, with site-wide scans and also through integration in our CI/CD pipeline. +- We follow the best practices of the Drupal community, which includes accessibility. ## When we do this -- We strive to produce work that is accessible to people of all abilities, regardless of client. However, we recognize that the level of accessibility compliance and prioritization can be influenced by budgetary and contractual implications. -- We aim to do accessibility work continuously, as part of our agile process. Accessibility scans should be performed on a per-ticket basis and signed off on before work is considered complete. -- We know that accessibility CANNOT BE left until the end of a project, but baked in throughout its lifespan. +- We strive to produce work that is accessible to people of all abilities, regardless of client. However, we recognize that the level of accessibility compliance and prioritization can be influenced by budgetary and contractual implications. +- We aim to do accessibility work continuously, as part of our agile process. Accessibility scans should be performed on a per-ticket basis and signed off on before work is considered complete. +- We know that accessibility CANNOT BE left until the end of a project, but baked in throughout its lifespan. ## General Accessibility Guidelines -- Form elements are built with meaningful labels and form buttons include descriptive values. -- Images should have meaningful alternative text ("alt tags") by default. We recommend making alt tags mandatory for content editors. -- Decorative images or images with no content use should either have a null alt tag (alt="") or rendered as CSS background images. -- Color should not be used as the sole method of conveying content or distinguishing visual elements. -- Color alone is not used to distinguish links from surrounding text unless the luminance contrast between the link and the surrounding text is at least 3:1 and an additional differentiation (e.g., it becomes underlined) is provided when the link is hovered over or receives focus. -- The page should be readable and functional when the text size is doubled. We use rem font-sizing (or another dynamic font unit) to make the text scales as expected when the web-page is zoomed-in. This also provides reliable text-resizing in smaller browser widths. -- Adequate line spacing (at least 1/2 the height of the text) and paragraph spacing (1.5 times line spacing) is important for readability. +- Form elements are built with meaningful labels and form buttons include descriptive values. +- Images should have meaningful alternative text ("alt tags") by default. We recommend making alt tags mandatory for content editors. +- Decorative images or images with no content use should either have a null alt tag (alt="") or rendered as CSS background images. +- Color should not be used as the sole method of conveying content or distinguishing visual elements. +- Color alone is not used to distinguish links from surrounding text unless the luminance contrast between the link and the surrounding text is at least 3:1 and an additional differentiation (e.g., it becomes underlined) is provided when the link is hovered over or receives focus. +- The page should be readable and functional when the text size is doubled. We use rem font-sizing (or another dynamic font unit) to make the text scales as expected when the web-page is zoomed-in. This also provides reliable text-resizing in smaller browser widths. +- Adequate line spacing (at least 1/2 the height of the text) and paragraph spacing (1.5 times line spacing) is important for readability. ## Resources -- [CivicActions Accessibility Site](https://accessibility.civicactions.com): Please visit and bookmark, it contains a wealth of information about open source and web accessibility. -- [Drupal's Accessibility Landing Page](https://www.drupal.org/docs/getting-started/accessibility) -- [W3C's WCAG 2 Overview](http://www.w3.org/WAI/intro/wcag) +- [CivicActions Accessibility Site](https://accessibility.civicactions.com): Please visit and bookmark, it contains a wealth of information about open source and web accessibility. +- [Drupal's Accessibility Landing Page](https://www.drupal.org/docs/getting-started/accessibility) +- [W3C's WCAG 2 Overview](http://www.w3.org/WAI/intro/wcag) diff --git a/practice-areas/engineering/drupal/README.md b/practice-areas/engineering/drupal/README.md index ce5ecc9a50..9d5f7c2b8a 100644 --- a/practice-areas/engineering/drupal/README.md +++ b/practice-areas/engineering/drupal/README.md @@ -22,15 +22,15 @@ CivicActions adopted a standard practice of setting Objectives and Key Results i We are still in the process of optimizing our OKR practices. That said, Drupal practice area participants have developed practice area OKRs that merge with CivicActions organizational objectives. OKR discussions happen frequently in practice area calls and via: -- [Trello board](https://trello.com/b/MH1OIHzV/drupal-practice-area-okrs) -- [Culture amp](https://civicactions.cultureamp.com/performance/new_goals/department) +- [Trello board](https://trello.com/b/MH1OIHzV/drupal-practice-area-okrs) +- [Culture amp](https://civicactions.cultureamp.com/performance/new_goals/department) ## Skillsbase: complete a self-assessment of your Drupal skills Please complete a skills assessment as part of your onboarding to the Drupal practice area if you have not done so. -- [Drupal Skills Categories](https://app.skills-base.com/skillcategories/view/id/16) -- [Skills Assessment](https://app.skills-base.com/people/view#assessments) +- [Drupal Skills Categories](https://app.skills-base.com/skillcategories/view/id/16) +- [Skills Assessment](https://app.skills-base.com/people/view#assessments) ## Got a Drupal problem? We're all here to help! @@ -48,10 +48,10 @@ We strongly encourage all CivicActioners to look for opportunities to give back ### Update your drupal.org profile -- Go to . -- Log into your drupal.org account (create one if you do not have one). -- Align it with CivicActions in the "Work" section: Edit profile > Then expand the Work section > Type in "CivicActions" and your Job title. -- Align your role with CivicActions in the "[Contributor roles](https://www.drupal.org/community/contributor-guide/find-your-role)" section: Edit profile > Then expand the Contributor roles section > Type in "CivicActions" in "Organization support". +- Go to . +- Log into your drupal.org account (create one if you do not have one). +- Align it with CivicActions in the "Work" section: Edit profile > Then expand the Work section > Type in "CivicActions" and your Job title. +- Align your role with CivicActions in the "[Contributor roles](https://www.drupal.org/community/contributor-guide/find-your-role)" section: Edit profile > Then expand the Contributor roles section > Type in "CivicActions" in "Organization support". ### Contribution to drupal.org modules and themes diff --git a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md index 1ea8d2f3ec..5f33f844bc 100644 --- a/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md +++ b/practice-areas/engineering/drupal/drupal-contrib-first-module-development.md @@ -10,9 +10,9 @@ When a new module is needed we try to follow [Contrib First](../../../common-pra 2. Gather requirements and identify MVP vs nice-to-haves 3. Search for existing modules that might solve the problem. (It might be easier to stretch an existing module than build a new one) 4. If opting to build a new module: - - Choose a meaningful search engine friendly module name. (crowd sourcing name suggestions is recommended) - - Create the Drupal project on Drupal.org - - Populate the project page with a description of what is coming. List supporters as CivicActions and the client [directions](./README.md#contribution-to-drupalorg-modules-and-themes). If the client does not have a drupal.org page, get help from your PM to encourage them to create one. + - Choose a meaningful search engine friendly module name. (crowd sourcing name suggestions is recommended) + - Create the Drupal project on Drupal.org + - Populate the project page with a description of what is coming. List supporters as CivicActions and the client [directions](./README.md#contribution-to-drupalorg-modules-and-themes). If the client does not have a drupal.org page, get help from your PM to encourage them to create one. 5. Populate the issue queue on the Drupal project with "Feature requests". Keep them as atomic as possible. Mark any that are part of the MVP as "major". Create issues for any improvement ideas that emerge. They don't all have to be acted on, but they help shape the road map for where you want the module to go. 6. Close the issues as you go and be sure to credit yourself, CivicActions, and the client. 7. Begin with alpha releases. Ideally when all your MVP/major issues are closed, you are ready for the official release. diff --git a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md index 3baf83b13e..17ef8e1397 100644 --- a/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md +++ b/practice-areas/engineering/drupal/drupal-developer-tips-for-getting-the-most-out-of-open-source.md @@ -12,43 +12,43 @@ I [recently suggested](../drupal/most-important-decision-in-developing-a-drupal- Before wading into coding, it's important to take a good hard look at what's out there. For each area of functionality you're going to develop, the following decision-making steps can help focus your work. -- **Existing modules and configuration** Is there an existing well-coded module that meets the need? Can the functionality be delivered through pure configuration? If so, do that. -- **New development** Is the functionality, or is a significant aspect of it, a common need suitable to and worthy of solving in a generic way? +- **Existing modules and configuration** Is there an existing well-coded module that meets the need? Can the functionality be delivered through pure configuration? If so, do that. +- **New development** Is the functionality, or is a significant aspect of it, a common need suitable to and worthy of solving in a generic way? - - **Existing module** Is there an existing well-coded module that covers most of the need? If so, use the existing to provide the bulk of the solution. + - **Existing module** Is there an existing well-coded module that covers most of the need? If so, use the existing to provide the bulk of the solution. - - **Existing patch** Search the drupal.org issue queue for issues similar to yours. Does a patch exist that you could use, test, improve, and review? If so, do so. - - **New patch(es)** If not, produce a patch or patches on the module to achieve the changes as [Contrib First](../../../common-practices-tools/contribution/contrib-first.md). Contribute the patch to a new or existing issue with ample explanation. + - **Existing patch** Search the drupal.org issue queue for issues similar to yours. Does a patch exist that you could use, test, improve, and review? If so, do so. + - **New patch(es)** If not, produce a patch or patches on the module to achieve the changes as [Contrib First](../../../common-practices-tools/contribution/contrib-first.md). Contribute the patch to a new or existing issue with ample explanation. - - **New contrib module** If there is no existing module to cover the need, consider a small, focused new module for contributing back on drupal.org as [Contrib First](../../../common-practices-tools/contribution/contrib-first.md). See [guidance on building a module as Contrib First](./drupal-contrib-first-module-development.md). - - **New contrib module set** In cases where the problem is large, avoid producing a large, monolithic module that does a lot of distinct things. Instead, break the work into small distinct modules, not necessarily packaged in the same project. Wherever possible, rely on existing well coded API modules as components of your solution. + - **New contrib module** If there is no existing module to cover the need, consider a small, focused new module for contributing back on drupal.org as [Contrib First](../../../common-practices-tools/contribution/contrib-first.md). See [guidance on building a module as Contrib First](./drupal-contrib-first-module-development.md). + - **New contrib module set** In cases where the problem is large, avoid producing a large, monolithic module that does a lot of distinct things. Instead, break the work into small distinct modules, not necessarily packaged in the same project. Wherever possible, rely on existing well coded API modules as components of your solution. -- **Theme modifications** Is it a presentation-type change? Consider implementing at the theme level. However, avoid introducing new logic or functionality at the theme level. The following should be avoided wherever possible at the theme level: - - Load new data. - - Implement conditional logic. -- **Custom module** Is it not a presentation-type change and not suitable for contributed (generic) module development? Consider writing a custom module for use only on this site or - if feasible - for use on various sites that you maintain. +- **Theme modifications** Is it a presentation-type change? Consider implementing at the theme level. However, avoid introducing new logic or functionality at the theme level. The following should be avoided wherever possible at the theme level: + - Load new data. + - Implement conditional logic. +- **Custom module** Is it not a presentation-type change and not suitable for contributed (generic) module development? Consider writing a custom module for use only on this site or - if feasible - for use on various sites that you maintain. In summary: -- Wherever possible, use or improve what already exists (existing contrib modules) before building anew. -- When it's necessary to build anew, focus first on doing so to a high, generic, contributed standard. -- Try to produce custom (site-specific closed source) modules only when the needs are limited in scope and truly specific to the site. -- Try to save the theme layer for what it's intended for--final presentation, look and feel. -- When we work on a FOSS contribution for a client(s), all of the work should be billable to that client. When doing maintenance on a contribution for no particular client, that work should be reccorded as community participation (PRODEV_COMPART -> Community Participation). You will need to ask to be added to your options in Slack #unanet. +- Wherever possible, use or improve what already exists (existing contrib modules) before building anew. +- When it's necessary to build anew, focus first on doing so to a high, generic, contributed standard. +- Try to produce custom (site-specific closed source) modules only when the needs are limited in scope and truly specific to the site. +- Try to save the theme layer for what it's intended for--final presentation, look and feel. +- When we work on a FOSS contribution for a client(s), all of the work should be billable to that client. When doing maintenance on a contribution for no particular client, that work should be reccorded as community participation (PRODEV_COMPART -> Community Participation). You will need to ask to be added to your options in Slack #unanet. ## Patching vs. hacking vs. forking Changes we might make to existing modules fall into three general categories, which have very distinct implications. -- **Patches** A patch is a contribution to a project that can reasonably be expected to be accepted. A patch is generic (not specific to a particular site). It's contributed back to the codebase with the confidence that in all likelihood it will be accepted. Thus, a patch is a short-term change--once it is accepted, the codebase will again be clean. -- **Hacks** A hack is a small change made to a file or files in the knowledge that it is unlikely to be accepted as a contribution to the original project. A hack may be made e.g. to provide customizations required by a client. Hacks may e.g. cause code conflicts when code is updated to a new version. Hacks have permanent costs--they must be maintained in perpetuity. -- **Forks** A fork is extensive customizations made to an existing project to the extent that the codebase is now fundamentally customized. A fork converts an existing project into a custom module that must be permanently maintained on a custom basis for the site in question. Forking implies major long term costs and largely undermines the benefits of open source development, e.g., minimization of future maintenance and upgrade costs. Forks should be avoided whenever possible. +- **Patches** A patch is a contribution to a project that can reasonably be expected to be accepted. A patch is generic (not specific to a particular site). It's contributed back to the codebase with the confidence that in all likelihood it will be accepted. Thus, a patch is a short-term change--once it is accepted, the codebase will again be clean. +- **Hacks** A hack is a small change made to a file or files in the knowledge that it is unlikely to be accepted as a contribution to the original project. A hack may be made e.g. to provide customizations required by a client. Hacks may e.g. cause code conflicts when code is updated to a new version. Hacks have permanent costs--they must be maintained in perpetuity. +- **Forks** A fork is extensive customizations made to an existing project to the extent that the codebase is now fundamentally customized. A fork converts an existing project into a custom module that must be permanently maintained on a custom basis for the site in question. Forking implies major long term costs and largely undermines the benefits of open source development, e.g., minimization of future maintenance and upgrade costs. Forks should be avoided whenever possible. In weighing potential changes, it's essential to figure out what kind of change we're making and to carefully weigh costs and benefits, ensuring that the client too is aware of long term implications. At every stage, we should ask: -- Can this change be made through API methods rather than code changes? For example, is there a hook available that could be used in a custom module to achieve the change without changing existing modules? -- If not, can this change be made cleanly through a patch? -- If not, is the benefit that would result from this change truly worth the long term costs of a hack or a fork? +- Can this change be made through API methods rather than code changes? For example, is there a hook available that could be used in a custom module to achieve the change without changing existing modules? +- If not, can this change be made cleanly through a patch? +- If not, is the benefit that would result from this change truly worth the long term costs of a hack or a fork? Similar considerations apply when considering custom modules or overrides at the theme level. We should work with the client to ensure they understand that each hack, fork, custom module, and extensive theme override increases long term costs, especially of upgrades, and cumulatively can risk undermining some of the benefits of working with open source tools. @@ -56,31 +56,31 @@ Similar considerations apply when considering custom modules or overrides at the Getting patches accepted and applied takes a lot of time and effort. But it's time well spent. It's part of the cost of working with open source. Often, the time required to initially code a solution through a patch is only a fraction of the total time that will be required to get that patch accepted. Ideally, these are costs that we should build into development. Some keys to making this work: -- **Make your changes generic** Avoid site-specific hacks wherever possible. Do this e.g. through adding configuration options. -- **Work with the current development branch** Active development on a particular module may have passed on from the Drupal version your site is in. If so, take the time to convert your patch to the active development version. If you can get it applied there, you might be able to backport it. Even if a backport doesn't get applied, you're still doing well. When the site you're working on is upgraded in future, there'll be one less patch to worry about. -- **Break up patches** When submitting patches, it's essential that you break them up into logically distinct issues. Yes, it's a lot more work. Yes, it's tempting to only roll a single patch for the various changes you might make to a module--new features, bug fixes, etc. But doing so will often sink any chance you have of getting the patch applied. How to do this in practice? Say you maintain an SVN repository of the site you're working on, as many Drupal development shops do. - - Maintain (outside of SVN) a clean checkout of the module in question for each issue. In that checkout, make only the changes you need for that issue. Generate a patch. - - In your SVN repository checkout, apply each of the patches you've generated. You end up with the cumulative total of the patches, but you're able to keep them distinct. -- **Communicate outside the patch queue** Connect with others in [drupal Slack](https://www.drupal.org/slack). Participate in or initiate discussions on [groups.drupal.org](https://groups.drupal.org/). Selectively and respectfully contact other developers via email to ask for feedback. -- **Follow up** It's essential that you follow up on the patches you post. Answer questions. Refresh patches. -- **Request CVS access** If it looks like the maintainer could use some help, request CVS write access to the project. Wait until you've already contributed some sound patches. Then say, e.g., "I'm going to be working a lot with this module for the next few weeks/months and will be contributing a lot of patches. I'll always work through the issue queue. Could I get CVS access?" -- **Co-maintain** If it looks like you'll be working in the longer term on the project, offer to be a co-maintainer of a module. Like requesting CVS write access, this works best if you've started small by proving yourself through e.g. some pure bug fix patches or small commonly needed features. +- **Make your changes generic** Avoid site-specific hacks wherever possible. Do this e.g. through adding configuration options. +- **Work with the current development branch** Active development on a particular module may have passed on from the Drupal version your site is in. If so, take the time to convert your patch to the active development version. If you can get it applied there, you might be able to backport it. Even if a backport doesn't get applied, you're still doing well. When the site you're working on is upgraded in future, there'll be one less patch to worry about. +- **Break up patches** When submitting patches, it's essential that you break them up into logically distinct issues. Yes, it's a lot more work. Yes, it's tempting to only roll a single patch for the various changes you might make to a module--new features, bug fixes, etc. But doing so will often sink any chance you have of getting the patch applied. How to do this in practice? Say you maintain an SVN repository of the site you're working on, as many Drupal development shops do. + - Maintain (outside of SVN) a clean checkout of the module in question for each issue. In that checkout, make only the changes you need for that issue. Generate a patch. + - In your SVN repository checkout, apply each of the patches you've generated. You end up with the cumulative total of the patches, but you're able to keep them distinct. +- **Communicate outside the patch queue** Connect with others in [drupal Slack](https://www.drupal.org/slack). Participate in or initiate discussions on [groups.drupal.org](https://groups.drupal.org/). Selectively and respectfully contact other developers via email to ask for feedback. +- **Follow up** It's essential that you follow up on the patches you post. Answer questions. Refresh patches. +- **Request CVS access** If it looks like the maintainer could use some help, request CVS write access to the project. Wait until you've already contributed some sound patches. Then say, e.g., "I'm going to be working a lot with this module for the next few weeks/months and will be contributing a lot of patches. I'll always work through the issue queue. Could I get CVS access?" +- **Co-maintain** If it looks like you'll be working in the longer term on the project, offer to be a co-maintainer of a module. Like requesting CVS write access, this works best if you've started small by proving yourself through e.g. some pure bug fix patches or small commonly needed features. ## Reaping the benefits Coding to high standards and contributing back has very tangible benefits, the type that project managers and bookkeepers can understand, including: -- Reduced upgrade and maintenance costs. -- Greater stability. -- Better performance e.g. due to lower code footprints. -- Reduced reliance on a particular solution provider. +- Reduced upgrade and maintenance costs. +- Greater stability. +- Better performance e.g. due to lower code footprints. +- Reduced reliance on a particular solution provider. But there are also a lot of less direct or tangible but equally important rewards. -- _Recognition_ By contributing back the work you do, you can gain recognition as a leader in the specific areas you've focused on. -- _Further work_ As your work gains profile, you may attract new contracts in the same areas, allowing you to continue to extend solutions through a series of projects for different clients. -- _Learning and skills_ Peer review and the challenge of coding generic solutions generates ideas and knowledge and helps you keep up to date. -- _Contacts_ Engaging with the community to work on solving common problems helps connect you with others interested in the same things you are. These contacts can really help in finding new projects to take on. -- _Satisfaction_ There's a definite satisfaction that comes from feeling you've not only solved a problem but you've solved it well. +- _Recognition_ By contributing back the work you do, you can gain recognition as a leader in the specific areas you've focused on. +- _Further work_ As your work gains profile, you may attract new contracts in the same areas, allowing you to continue to extend solutions through a series of projects for different clients. +- _Learning and skills_ Peer review and the challenge of coding generic solutions generates ideas and knowledge and helps you keep up to date. +- _Contacts_ Engaging with the community to work on solving common problems helps connect you with others interested in the same things you are. These contacts can really help in finding new projects to take on. +- _Satisfaction_ There's a definite satisfaction that comes from feeling you've not only solved a problem but you've solved it well. In short: if contributing back is an afterthought at best, we're missing out on most of the benefit of open source, please [Contrib First](../../../common-practices-tools/contribution/contrib-first.md) if possible. diff --git a/practice-areas/engineering/drupal/drupal-for-drupal-engineers.md b/practice-areas/engineering/drupal/drupal-for-drupal-engineers.md index d348915517..01208bf0a6 100644 --- a/practice-areas/engineering/drupal/drupal-for-drupal-engineers.md +++ b/practice-areas/engineering/drupal/drupal-for-drupal-engineers.md @@ -20,8 +20,8 @@ If you need to create your own fix update the issue accordingly. Your project's technical lead can show you where any patch files are stored in your project and explain how they are applied. -- [https://www.drupal.org/community/contributor-guide/reference-information/quick-info/life-cycle-of-an-issue](https://www.drupal.org/community/contributor-guide/reference-information/quick-info/life-cycle-of-an-issue) -- [https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) +- [https://www.drupal.org/community/contributor-guide/reference-information/quick-info/life-cycle-of-an-issue](https://www.drupal.org/community/contributor-guide/reference-information/quick-info/life-cycle-of-an-issue) +- [https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) ## Version control and the code review process @@ -60,8 +60,8 @@ CivicActions adopted a standard practice of setting Objectives and Key Results i We are still in the process of optimizing our practices in this area. Drupal practice area OKRs have been developed that align with CivicActions organizational objectives. OKR discussions happen frequently in practice area calls and -- Trello board (read-only): [https://trello.com/b/MH1OIHzV/drupal-practice-area-okrs](https://trello.com/b/MH1OIHzV/drupal-practice-area-okrs) -- Culture amp: [https://civicactions.cultureamp.com/performance/new_goals/department](https://civicactions.cultureamp.com/performance/new_goals/department) +- Trello board (read-only): [https://trello.com/b/MH1OIHzV/drupal-practice-area-okrs](https://trello.com/b/MH1OIHzV/drupal-practice-area-okrs) +- Culture amp: [https://civicactions.cultureamp.com/performance/new_goals/department](https://civicactions.cultureamp.com/performance/new_goals/department) ### Skillsbase: Complete a self-assessment of your Drupal skills @@ -109,7 +109,7 @@ Checking the box and adding the organization and customer will ensure that any c ### External Resources -- Drupalize.me -- Acquia Academy -- Buildamodule Youtube channel -- D.o helpful links +- Drupalize.me +- Acquia Academy +- Buildamodule Youtube channel +- D.o helpful links diff --git a/practice-areas/engineering/drupal/drupal-for-everyone.md b/practice-areas/engineering/drupal/drupal-for-everyone.md index 5f025ac92a..58e2997e7d 100644 --- a/practice-areas/engineering/drupal/drupal-for-everyone.md +++ b/practice-areas/engineering/drupal/drupal-for-everyone.md @@ -26,18 +26,18 @@ From the first year of operations, CivicActions was committed to openness. This Drupal is an extremely popular open-source content management system (CMS) used for building websites and applications. There are many reasons why some of the most high-trafficked and essential web sites on the internet are built on Drupal: -- **Customizability:** Drupal is highly customizable in terms of functionality, layout, and design. This makes it an ideal choice for complex websites with specific requirements. +- **Customizability:** Drupal is highly customizable in terms of functionality, layout, and design. This makes it an ideal choice for complex websites with specific requirements. -- **Scalability:** Drupal is highly scalable. It can handle high traffic loads and complex data manipulation. It is used by many high-profile websites and can support businesses as they grow. +- **Scalability:** Drupal is highly scalable. It can handle high traffic loads and complex data manipulation. It is used by many high-profile websites and can support businesses as they grow. -- **Community and Support:** Drupal has a large and active community of developers contributing to the codebase. The community is supportive and helps keep the platform up to date. +- **Community and Support:** Drupal has a large and active community of developers contributing to the codebase. The community is supportive and helps keep the platform up to date. -- **Security:** Drupal has a strong reputation for its focus on security. It is a proactive community that takes security vulnerabilities seriously. Regular updates are released to address any potential issues. +- **Security:** Drupal has a strong reputation for its focus on security. It is a proactive community that takes security vulnerabilities seriously. Regular updates are released to address any potential issues. -- **Built-in Web Services:** Drupal 8 and later versions come with built-in web services. This makes it a great choice for building headless applications where the front-end is decoupled from the backend, using Drupal to serve content via an API. +- **Built-in Web Services:** Drupal 8 and later versions come with built-in web services. This makes it a great choice for building headless applications where the front-end is decoupled from the backend, using Drupal to serve content via an API. -- **Multilingual Capabilities:** Drupal provides robust multilingual features. Drupal is an excellent choice for international and multilingual sites. +- **Multilingual Capabilities:** Drupal provides robust multilingual features. Drupal is an excellent choice for international and multilingual sites. -- **SEO Friendly:** Drupal's flexibility and configuration options make it SEO-friendly. Drupal websites can have high search engine rankings. +- **SEO Friendly:** Drupal's flexibility and configuration options make it SEO-friendly. Drupal websites can have high search engine rankings. -- **Content Workflow Management:** Drupal provides tools to manage the workflows of content creation. These tools enable efficient collaboration among multiple users. +- **Content Workflow Management:** Drupal provides tools to manage the workflows of content creation. These tools enable efficient collaboration among multiple users. diff --git a/practice-areas/engineering/drupal/drupal-for-project-teams.md b/practice-areas/engineering/drupal/drupal-for-project-teams.md index 1c59f978de..89450f9c5a 100644 --- a/practice-areas/engineering/drupal/drupal-for-project-teams.md +++ b/practice-areas/engineering/drupal/drupal-for-project-teams.md @@ -14,15 +14,15 @@ The /user/login path will bring you to the form to log in to your drupal site. D As a content management system, Drupal's primary purpose is to allow users to create content with as little technical knowledge as possible. Some of the tools that it uses to allow users to create meaningful content are listed below. As a project team, part of our responsibility is to tailor these tools to our client's needs. -- **Entity Types, Bundles & Entities:** In Drupal an entity type is a grouping of fields. Bundles are extensions of entity types, or sub-types. Entities are then instances of an entity type/bundle. For instance, an entity type can have several fields where editors or site administrators can enter content or other data. When these fields are filled out and submitted, an entity is created with the data from the fields. For those familiar with object-oriented patterns, An entity type can be thought of as a class. A bundle would be a subclass or extended class of the entity type. An entity would then be an instance or object of those classes. [Read more about entities.](https://www.drupal.org/docs/user_guide/en/planning-data-types.html) [Read more about the Entity API.](https://www.drupal.org/docs/drupal-apis/entity-api/introduction-to-entity-api-in-drupal-8) +- **Entity Types, Bundles & Entities:** In Drupal an entity type is a grouping of fields. Bundles are extensions of entity types, or sub-types. Entities are then instances of an entity type/bundle. For instance, an entity type can have several fields where editors or site administrators can enter content or other data. When these fields are filled out and submitted, an entity is created with the data from the fields. For those familiar with object-oriented patterns, An entity type can be thought of as a class. A bundle would be a subclass or extended class of the entity type. An entity would then be an instance or object of those classes. [Read more about entities.](https://www.drupal.org/docs/user_guide/en/planning-data-types.html) [Read more about the Entity API.](https://www.drupal.org/docs/drupal-apis/entity-api/introduction-to-entity-api-in-drupal-8) -- **Nodes:** A node is an entity type that is provided by Drupal core. Most content on most sites is going to be stored as nodes. Nodes can be further divided into other bundles such as articles, blog posts, or other custom content-types (bundles). [Read more about nodes.](https://www.drupal.org/docs/core-modules-and-themes/core-modules/node-module/about-nodes) +- **Nodes:** A node is an entity type that is provided by Drupal core. Most content on most sites is going to be stored as nodes. Nodes can be further divided into other bundles such as articles, blog posts, or other custom content-types (bundles). [Read more about nodes.](https://www.drupal.org/docs/core-modules-and-themes/core-modules/node-module/about-nodes) -- **Menus:** Menus are collections of links used for navigation in websites. Drupal comes standard with several menus including the main navigation. Links can be added to or removed from menus using the admin interface. [Read more about menus.](https://www.drupal.org/docs/user_guide/en/menu-concept.html) +- **Menus:** Menus are collections of links used for navigation in websites. Drupal comes standard with several menus including the main navigation. Links can be added to or removed from menus using the admin interface. [Read more about menus.](https://www.drupal.org/docs/user_guide/en/menu-concept.html) -- **Taxonomy:** Taxonomy is a way to categorize or classify different content on a site. Taxonomy terms provide a list of vocabularies or allow users to add new vocabulary on the fly that pieces of content can be "tagged" with. [Read more about taxonomy.](https://www.drupal.org/docs/user_guide/en/structure-taxonomy.html) +- **Taxonomy:** Taxonomy is a way to categorize or classify different content on a site. Taxonomy terms provide a list of vocabularies or allow users to add new vocabulary on the fly that pieces of content can be "tagged" with. [Read more about taxonomy.](https://www.drupal.org/docs/user_guide/en/structure-taxonomy.html) -- **Aliases & Redirects:** These allow site builders and editors to create more readable urls to content on the site. So instead of seeing a path like /node/12345 you could specify an alias of /some-content-title. [Read more about aliases and redirects.](https://www.drupal.org/docs/user_guide/en/content-paths.html) +- **Aliases & Redirects:** These allow site builders and editors to create more readable urls to content on the site. So instead of seeing a path like /node/12345 you could specify an alias of /some-content-title. [Read more about aliases and redirects.](https://www.drupal.org/docs/user_guide/en/content-paths.html) ## Drupal site administration @@ -30,13 +30,13 @@ As a content management system, Drupal's primary purpose is to allow users to cr Being able to control which users are able to see or do different things on your site is one of the major benefits of using a CMS like Drupal. In Drupal this is handled by giving users certain roles which have certain permissions. Drupal comes with a few roles by default, they are: -- **Anonymous users:** Any user that visits your site who is not currently logged in. This role typically has very few permissions. Most of the permissions assigned to this role are going to be for viewing certain pieces of content. +- **Anonymous users:** Any user that visits your site who is not currently logged in. This role typically has very few permissions. Most of the permissions assigned to this role are going to be for viewing certain pieces of content. -- **Authenticated users:** These are users who are logged in to your site. Depending on the site, authenticated users could have many permissions, or they might have very few permissions - similar to anonymous users. +- **Authenticated users:** These are users who are logged in to your site. Depending on the site, authenticated users could have many permissions, or they might have very few permissions - similar to anonymous users. -- **Administrator:** This is typically the role that you give to users who should have full administrative privileges to the site. +- **Administrator:** This is typically the role that you give to users who should have full administrative privileges to the site. -- **Content Editor:** This role has been included by default since Drupal 9.3. This role provides for the management of content, media, and workflows. As with all roles, it can be modified to suit your needs. +- **Content Editor:** This role has been included by default since Drupal 9.3. This role provides for the management of content, media, and workflows. As with all roles, it can be modified to suit your needs. You also have the ability to create additional roles however you see fit. For example, maybe your site allows users to sign up to be able to make comments on certain pieces of content. You might want to create a new role for commenters that gives them permissions that are different from, or more limited than, content editors, but not as limited as "Authenticated users". diff --git a/practice-areas/engineering/drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md b/practice-areas/engineering/drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md index 8d1d318de3..8b1a529ea0 100644 --- a/practice-areas/engineering/drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md +++ b/practice-areas/engineering/drupal/most-important-decision-in-developing-a-drupal-site-contributed-vs-custom-development.md @@ -8,15 +8,15 @@ Note: _This was originally a blog post on the CivicActions site authored by [Ned When developing in Drupal, should we hack something together that's specific to a site? Or should we instead take the time to do things "right" by improving existing modules or writing our own new modules to contribute to the community? When is one of these options better than the other? How do we decide? It's a key set of questions. All but the most basic projects will require some level of new development. The way we approach this new development is probably _the most important factor_ in determining the long term value of our work, both for us and for our clients. It's a given that we'll first try to meet as much of the need as we can through existing, proven solutions. But there is always some need for customization. For smaller projects, new development might be: -- minor patches to existing modules -- some work on a custom theme -- possibly a small focused custom module. +- minor patches to existing modules +- some work on a custom theme +- possibly a small focused custom module. For larger projects, new development can include: -- a large custom theme -- several custom modules -- new modules for contribution back to the community. +- a large custom theme +- several custom modules +- new modules for contribution back to the community. What are some of the benefits and risks of custom vs. contributed development? Here's some suggestions on how they compare. @@ -85,8 +85,8 @@ Many of the same considerations apply when weighing the relative merits of theme In theory, the theme level should be concerned primarily or exclusively with presentation and display; _what_ is being displayed should be the concern of modules. This ideal separation is not always feasible in practice. Still, before weighing a theme down with API calls, it's a useful discipline to ask: is this better handled in a module? How would that be done? Simple tweaks at the theme level make total sense--the get the exact look and feel with little pain. But extensive overrides can reduce or undermine the benefits of the platform. Example: overriding the display of a form. It's relatively quick and easy to do, but has long-term implications: -- Future UI-level changes (for example, through CCK's field display management) may have unexpected results, or none at all. -- New modules may be turned on but have no way to affect the form without new custom coding. +- Future UI-level changes (for example, through CCK's field display management) may have unexpected results, or none at all. +- New modules may be turned on but have no way to affect the form without new custom coding. It may indeed be necessary to extensively customize a form if it's centrally important to the client. But can at least major pieces of this customization be done through an existing or if necessary a new API module, in ways applicable not just to this one form but to any form? @@ -94,18 +94,18 @@ It may indeed be necessary to extensively customize a form if it's centrally imp A large part of the challenge of providing the highest value to a client lies in teasing out the abstract problems embedded in the specificity of a client's project. Doing so is a skill that engineers can develop over time. It's not purely a technical question and ideally should involve the client, the project manager, and other members of the engineering team. Asking the right questions at the outset is key to ensuring the overall project is developed along a line where open sourcing the main thrust of development is a natural assumption. It can help to take a few steps back from the immediate details. What's the core of this need? Questions that can help tease out the generic core of a problem include: -- What is the basic need that this particular requirement answers? -- What are the few problems that anyone with a similar need would always face, regardless of the details? -- What would the required information/data look like, independent of how it's displayed? -- What is the earliest spot in the process of loading and building that this change could be made? Rather than tacking on or overriding in a large way at the end, could we make this an integral part from the start? -- What is the minimum that we could do or change and still meet the need? -- Is this problem really several distinct problems that just look like one because they're tied up in the same UI/output/mockup/image? +- What is the basic need that this particular requirement answers? +- What are the few problems that anyone with a similar need would always face, regardless of the details? +- What would the required information/data look like, independent of how it's displayed? +- What is the earliest spot in the process of loading and building that this change could be made? Rather than tacking on or overriding in a large way at the end, could we make this an integral part from the start? +- What is the minimum that we could do or change and still meet the need? +- Is this problem really several distinct problems that just look like one because they're tied up in the same UI/output/mockup/image? Questions that can help clarify whether a particular problem lends itself to an abstract, contributed solution include: -- Is the basic problem or need likely to recur elsewhere on the site or on other sites? -- Will a significant amount of time and code be required? -- Is this problem close to the core of what the organization/site is all about? +- Is the basic problem or need likely to recur elsewhere on the site or on other sites? +- Will a significant amount of time and code be required? +- Is this problem close to the core of what the organization/site is all about? A "yes" to one or more of these questions would indicate at least the potential to build out a solution coded to a high, generic, open source standard, rather than custom code at the module or theme level. diff --git a/practice-areas/engineering/engineering-calls.md b/practice-areas/engineering/engineering-calls.md index 127cc49e5a..beadd08b4f 100644 --- a/practice-areas/engineering/engineering-calls.md +++ b/practice-areas/engineering/engineering-calls.md @@ -16,21 +16,21 @@ The engineering call follows an [open space format](https://www.facilitator.scho In advance of the call, or in the first couple of minutes of the call: -- Add any/all topics you want to talk about to [our Trello board](https://trello.com/b/wd0WmGlx/engineering-meeting) -- Upvote any Trello topics that you would be interested in talking about +- Add any/all topics you want to talk about to [our Trello board](https://trello.com/b/wd0WmGlx/engineering-meeting) +- Upvote any Trello topics that you would be interested in talking about Topics can be anything you are interested in learning, sharing or chatting about: -- You don't need to be an expert or have anything to contribute (except questions!) to suggest a topic -- Examples of topics could range from: - - a deep dive into a specific language feature - - a discussion on a new technology - - group debugging of some gnarly bug - - exploring process improvement ideas - - or anything else! +- You don't need to be an expert or have anything to contribute (except questions!) to suggest a topic +- Examples of topics could range from: + - a deep dive into a specific language feature + - a discussion on a new technology + - group debugging of some gnarly bug + - exploring process improvement ideas + - or anything else! On the call we will: -- Split into Zoom breakout rooms to discuss through each topic -- Feel free to change groups if you like: this is encouraged! -- Regroup for a few minutes at the end to catch up on any insight we want to share +- Split into Zoom breakout rooms to discuss through each topic +- Feel free to change groups if you like: this is encouraged! +- Regroup for a few minutes at the end to catch up on any insight we want to share diff --git a/practice-areas/engineering/git.md b/practice-areas/engineering/git.md index d19ccbfa79..21edce0f7e 100644 --- a/practice-areas/engineering/git.md +++ b/practice-areas/engineering/git.md @@ -10,100 +10,100 @@ As you may already know, Git is a source code versioning system that lets you lo Here are some references to review if you are unfamiliar with it. -- [Pro Git book](https://git-scm.com/) -- [Github resources](https://docs.github.com/en/get-started/quickstart/git-and-github-learning-resources) -- [Getting Git Right](https://www.atlassian.com/git/) -- [Version Control with Git book](https://www.amazon.com/Version-Control-Git-collaborative-development/dp/1449316387) +- [Pro Git book](https://git-scm.com/) +- [Github resources](https://docs.github.com/en/get-started/quickstart/git-and-github-learning-resources) +- [Getting Git Right](https://www.atlassian.com/git/) +- [Version Control with Git book](https://www.amazon.com/Version-Control-Git-collaborative-development/dp/1449316387) Here are more advanced resources to learn "how Git works" at a lower level, which is helpful for building your mental model for using rebasing, reflog, etc. -- -- [Non-video companion to the first half](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) +- +- [Non-video companion to the first half](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) ## Git best practices _Note: your project may include other code review practices. Please review your project developer/contributor documentation!_ -- Atomic commits: - - Generally commits should be as small as possible. - - The code should be in a functional state after each commit (even if incomplete). Avoid committing code which will won't run at all. -- Write good commit messages. A good commit message should: - - Reference the associated ticket ID using a prefix, such as `ABC-123:`. This makes it easier to locate tickets from git log/blame output as well as helping make sure all work is associated with a ticket. - - Have a one line (max 80 char) title/summary of the change, followed by a blank line and then further detail which should: - - Explain the reason(s) for the change. - - Detail what changed and any consequences of this (on code, data, users, security, etc.). Include any key terms that would help a future person searching commits. - - Often this will include the same detail that you might include in code comments. -- Feature branches, pull requests (PR) and merge requests (MR): - - These should contain a closely-related series of commits that solves a single problem. Avoid including changes that are unrelated. - - Most often a single (well scoped) ticket will be resolved in a single PR or MR. - - However, it is good to break larger changes over multiple PRs or MRs that each address a logical piece of the whole. This can make the code easier to review. - - When merging PRs and MRs, we prefer a rebase workflow with fast-forward merges (rather than a merge commit) since this retains a clean and linear commit history which can be helpful for future engineers. - - For small PRs or MRs where there isn't much commit detail, using a squash-merge approach can also be fine. -- We rebase commits on a feature branch for 2 reasons: - - To update the feature branch on top of more recent changes in master so that it can be easily merged when ready. - - To adjust the commits on the branch with an interactive rebase. For example: - - Squashing 2 together that make more sense as one change. - - Splitting a large commit into 2+ smaller ones. - - Adjusting the wording of commit messages (see above). - - Dropping any temporary/scratch commits. - - When rebasing a feature branch, it's encouraged to leave commits showing earlier attempts, even if you later found a better approach. - - This helps "tell the story" of the change. Someone digging though the history may wonder why the first approach didn't work. - - It also leaves the code available in the history in case you later find a use for that work. +- Atomic commits: + - Generally commits should be as small as possible. + - The code should be in a functional state after each commit (even if incomplete). Avoid committing code which will won't run at all. +- Write good commit messages. A good commit message should: + - Reference the associated ticket ID using a prefix, such as `ABC-123:`. This makes it easier to locate tickets from git log/blame output as well as helping make sure all work is associated with a ticket. + - Have a one line (max 80 char) title/summary of the change, followed by a blank line and then further detail which should: + - Explain the reason(s) for the change. + - Detail what changed and any consequences of this (on code, data, users, security, etc.). Include any key terms that would help a future person searching commits. + - Often this will include the same detail that you might include in code comments. +- Feature branches, pull requests (PR) and merge requests (MR): + - These should contain a closely-related series of commits that solves a single problem. Avoid including changes that are unrelated. + - Most often a single (well scoped) ticket will be resolved in a single PR or MR. + - However, it is good to break larger changes over multiple PRs or MRs that each address a logical piece of the whole. This can make the code easier to review. + - When merging PRs and MRs, we prefer a rebase workflow with fast-forward merges (rather than a merge commit) since this retains a clean and linear commit history which can be helpful for future engineers. + - For small PRs or MRs where there isn't much commit detail, using a squash-merge approach can also be fine. +- We rebase commits on a feature branch for 2 reasons: + - To update the feature branch on top of more recent changes in master so that it can be easily merged when ready. + - To adjust the commits on the branch with an interactive rebase. For example: + - Squashing 2 together that make more sense as one change. + - Splitting a large commit into 2+ smaller ones. + - Adjusting the wording of commit messages (see above). + - Dropping any temporary/scratch commits. + - When rebasing a feature branch, it's encouraged to leave commits showing earlier attempts, even if you later found a better approach. + - This helps "tell the story" of the change. Someone digging though the history may wonder why the first approach didn't work. + - It also leaves the code available in the history in case you later find a use for that work. ### Git best practice resources -- -- +- +- ## Code review _Note: your project may include other code review practices. Please review your project developer/contributor documentation!_ -- Code reviews are shared between all developers. If you finish a ticket (or just want a break), check for outstanding PRs or MRs before picking up a new ticket. - - This is because getting shared awareness of the code others are working on helps the team learn and become more able to work across all areas of the codebase. - - If reviewing code that is outside your area of expertise, you can always ask for a second set of eyes. - - On most projects, code review is done at the same time as some level of functional testing using a review environment specific to the PR or MR. -- Review using a [phased process](https://sage.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) that starts at the big picture, giving feedback (as needed) and getting alignment (as needed) on one phase before moving on. This avoids excessive detail early on and is more helpful to the developer. +- Code reviews are shared between all developers. If you finish a ticket (or just want a break), check for outstanding PRs or MRs before picking up a new ticket. + - This is because getting shared awareness of the code others are working on helps the team learn and become more able to work across all areas of the codebase. + - If reviewing code that is outside your area of expertise, you can always ask for a second set of eyes. + - On most projects, code review is done at the same time as some level of functional testing using a review environment specific to the PR or MR. +- Review using a [phased process](https://sage.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) that starts at the big picture, giving feedback (as needed) and getting alignment (as needed) on one phase before moving on. This avoids excessive detail early on and is more helpful to the developer. 1. Is the idea behind the PR or MR sound? 2. Is the PR or MR architected correctly? 3. Is the PR or MR polished? -- For code that touches complex or risky areas, such as security or performance implications, it's great to have 2 or even 3 reviewers take a look before merging. -- Most coding standards should generally be applied automatically using code auto-formatting tools and/or reviewed automatically using code linting and code quality checking tools. - - If this is not the case on your project, add this in your CI pipeline! -- Quality code is human friendly (self documenting, maintainable, adaptable) -- Try to make at least one point for improvement: encourage conversation -- Call out good code: praise is valuable feedback -- Put feedback in the form of questions: encourage collaboration +- For code that touches complex or risky areas, such as security or performance implications, it's great to have 2 or even 3 reviewers take a look before merging. +- Most coding standards should generally be applied automatically using code auto-formatting tools and/or reviewed automatically using code linting and code quality checking tools. + - If this is not the case on your project, add this in your CI pipeline! +- Quality code is human friendly (self documenting, maintainable, adaptable) +- Try to make at least one point for improvement: encourage conversation +- Call out good code: praise is valuable feedback +- Put feedback in the form of questions: encourage collaboration ### Core review resources -- -- -- -- -- +- +- +- +- +- ## Standard Git workflow _Note: your project may include other Git workflows. Please review your project developer/contributor documentation!_ -- Our standard workflow uses: - - Trunk-based development with a single `master` branch, meaning no additional long lived branches (e.g. `stable`) that get repeated merges - - Short-lived feature branches living in developer forks with PRs or MRs for all work - - Feature branches should be prefixed with the related ticket ID. For example: `abc-123-my-feature`. - - We often rebase feature branches and use fast-forward merges -- We follow an [upstream first](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) practice for all development - this means: - - If the code you want to change is in an external library or module, contribute the change to that library first before bringing it into your actual project (e.g. by adding the patch to a build tool or adjusting the source to point to an upstream that includes the change) - - If you need to make a hotfix, make a PR or MR to the main `master` branch first before creating or patching a hotfix branch. -- Feature branches undergo both automatic and manual testing before being merged. This makes sure that master always passes tests. - - Testing often includes linting and unit and functional tests, as well as specialised tests such as security and accessibility scans. - - On most projects a dedicated review environment for each feature branch or PR or MR is created automatically and can be used for manual testing as well as stakeholder demos and user testing as needed to validate functionality before the branch is merged. +- Our standard workflow uses: + - Trunk-based development with a single `master` branch, meaning no additional long lived branches (e.g. `stable`) that get repeated merges + - Short-lived feature branches living in developer forks with PRs or MRs for all work + - Feature branches should be prefixed with the related ticket ID. For example: `abc-123-my-feature`. + - We often rebase feature branches and use fast-forward merges +- We follow an [upstream first](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) practice for all development - this means: + - If the code you want to change is in an external library or module, contribute the change to that library first before bringing it into your actual project (e.g. by adding the patch to a build tool or adjusting the source to point to an upstream that includes the change) + - If you need to make a hotfix, make a PR or MR to the main `master` branch first before creating or patching a hotfix branch. +- Feature branches undergo both automatic and manual testing before being merged. This makes sure that master always passes tests. + - Testing often includes linting and unit and functional tests, as well as specialised tests such as security and accessibility scans. + - On most projects a dedicated review environment for each feature branch or PR or MR is created automatically and can be used for manual testing as well as stakeholder demos and user testing as needed to validate functionality before the branch is merged. Compared to other documented workflows: -- [GitLab Flow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) - similar, although we prefer tags over environment branches -- [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) - similar, although we prefer rebase/fast-foward merges and don't deploy feature branches into production (but to review environments instead) -- [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) - not very similar: ours is much simpler and avoids long lived branches and repeated merges +- [GitLab Flow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) - similar, although we prefer tags over environment branches +- [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) - similar, although we prefer rebase/fast-foward merges and don't deploy feature branches into production (but to review environments instead) +- [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) - not very similar: ours is much simpler and avoids long lived branches and repeated merges ## Versioning releases @@ -113,26 +113,26 @@ For libraries, we use [semantic versioning](https://semver.org/). For web sites or applications we use an `vX.Y.Z` syntax with the following meaning: -- X: The sprint number -- Y: A zero-based counter indicating the number of releases to the stage environment -- Z: A zero-based counter indicating the number of hotfix releases to the prod environment +- X: The sprint number +- Y: A zero-based counter indicating the number of releases to the stage environment +- Z: A zero-based counter indicating the number of hotfix releases to the prod environment So in the normal release flow: -- First sprint, pushes to stage has tag v1.0.0 -- Further work and a v1.1.0 tag is created and pushed to stage -- Over the course of the sprint you might get v1.2.0, v1.3.0 etc -- Sprint 1 ends, v1.3.0 looks good, gets pushed to prod +- First sprint, pushes to stage has tag v1.0.0 +- Further work and a v1.1.0 tag is created and pushed to stage +- Over the course of the sprint you might get v1.2.0, v1.3.0 etc +- Sprint 1 ends, v1.3.0 looks good, gets pushed to prod In the case a subsequent hotfix is required: -- In Sprint 2 work continues on master, v2.0.0 tag gets pushed to stage etc. -- Meanwhile, critical bugfix needed on prod, so the v1.3.0 is branched to v1. - - There is no need for further suffixes in the branch name, since it's the only branch for sprint 1 - - We don't typically create these branches until they are needed, since it's hopefully rare to need critical hotfixes and we have a tag documenting the state of the release. -- Fix is pushed to master (i.e. upstream-first workflow), then cherry-picked to v1. -- Tag v1.3.1 is then created from the v1 branch, pushed to stage (or some dedicated hotfix stage environment) and then to prod. -- If another hotfix is needed, that commit would also be merged to master, cherry-picked into v1 and tagged v1.3.2 etc. +- In Sprint 2 work continues on master, v2.0.0 tag gets pushed to stage etc. +- Meanwhile, critical bugfix needed on prod, so the v1.3.0 is branched to v1. + - There is no need for further suffixes in the branch name, since it's the only branch for sprint 1 + - We don't typically create these branches until they are needed, since it's hopefully rare to need critical hotfixes and we have a tag documenting the state of the release. +- Fix is pushed to master (i.e. upstream-first workflow), then cherry-picked to v1. +- Tag v1.3.1 is then created from the v1 branch, pushed to stage (or some dedicated hotfix stage environment) and then to prod. +- If another hotfix is needed, that commit would also be merged to master, cherry-picked into v1 and tagged v1.3.2 etc. In a continuous deployment project these tags can be created automatically, or some other mechanism may be used to track releases. @@ -219,9 +219,9 @@ To make things easier, from the docs: > "To store your GPG key passphrase so you don't have to enter it every time you sign a commit, we recommend using the following tools: > -> - For Mac users, the [GPG Suite](https://gpgtools.org/) allows you to store your GPG key passphrase in the Mac OS Keychain. -> - For Windows users, the [Gpg4win](https://www.gpg4win.org/) integrates with other Windows tools. -> You can also manually configure [gpg-agent](https://linux.die.net/man/1/gpg-agent) to save your GPG key passphrase, but this doesn't integrate with Mac OS Keychain like ssh-agent and requires more setup." +> - For Mac users, the [GPG Suite](https://gpgtools.org/) allows you to store your GPG key passphrase in the Mac OS Keychain. +> - For Windows users, the [Gpg4win](https://www.gpg4win.org/) integrates with other Windows tools. +> You can also manually configure [gpg-agent](https://linux.die.net/man/1/gpg-agent) to save your GPG key passphrase, but this doesn't integrate with Mac OS Keychain like ssh-agent and requires more setup." Set a long cache time for the gpg-agent, so that you don't have to enter the passphrase every time: @@ -250,9 +250,9 @@ fatal: failed to write commit object GitLab, GitHub, and Bitbucket are services that provides remote access to Git repositories. In addition to hosting your code, these services provide additional features designed to help manage the software development lifecycle. These additional features include managing the sharing of code between different people, bug tracking, wiki space and other tools for "social coding". -- GitHub is a publicly available, free service which requires all code (unless you have a paid account) be made open. Anyone can see code you push to GitHub and offer suggestions for improvement. GitHub currently hosts the source code for tens of thousands of open source projects. CivicActions uses GitHub for all open source projects (except those which are better hosted on an open source community infrastructure), as well as internal, client or pro-bono projects that should be developed in public. +- GitHub is a publicly available, free service which requires all code (unless you have a paid account) be made open. Anyone can see code you push to GitHub and offer suggestions for improvement. GitHub currently hosts the source code for tens of thousands of open source projects. CivicActions uses GitHub for all open source projects (except those which are better hosted on an open source community infrastructure), as well as internal, client or pro-bono projects that should be developed in public. -- GitLab is an open source GitHub like software that organizations can use to provide internal management of Git repositories. CivicActions has setup a GitLab server for internal and client projects that should not be developed in public. +- GitLab is an open source GitHub like software that organizations can use to provide internal management of Git repositories. CivicActions has setup a GitLab server for internal and client projects that should not be developed in public. ### Moving code between GitLab, GitHub, and Bitbucket diff --git a/practice-areas/engineering/security-compliance.md b/practice-areas/engineering/security-compliance.md index d3c0bc7a93..48dcc2e2f3 100644 --- a/practice-areas/engineering/security-compliance.md +++ b/practice-areas/engineering/security-compliance.md @@ -16,35 +16,35 @@ We ensure that all [confidential information](../../company-policies/security.md Developers, themers and others working on a project site must: -- Be familiar with how to maintain configuration security - - For example, as described in Drupal's [securing your site](https://drupal.org/security/secure-configuration) page. -- Confirm correct role permissions and authorizations after changing settings affecting content/data access control. -- Ensure their code and development practices follow accepted secure coding standard. -- Ensure all changes that may affect site security are thoroughly tested before being made live. -- Engage - both give and receive - peer review of contributed code. -- Check for security advisories (e.g., [drupal.org/security](https://drupal.org/security)) for libraries/modules/packages, ensure they are upgraded where necessary. -- Understand common attack vectors, such as: - - [OWASP Top 10 Web Application Security Risks](https://owasp.org/www-project-top-ten/) - - [OWASP Top 10 API Security Risks](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) +- Be familiar with how to maintain configuration security + - For example, as described in Drupal's [securing your site](https://drupal.org/security/secure-configuration) page. +- Confirm correct role permissions and authorizations after changing settings affecting content/data access control. +- Ensure their code and development practices follow accepted secure coding standard. +- Ensure all changes that may affect site security are thoroughly tested before being made live. +- Engage - both give and receive - peer review of contributed code. +- Check for security advisories (e.g., [drupal.org/security](https://drupal.org/security)) for libraries/modules/packages, ensure they are upgraded where necessary. +- Understand common attack vectors, such as: + - [OWASP Top 10 Web Application Security Risks](https://owasp.org/www-project-top-ten/) + - [OWASP Top 10 API Security Risks](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) ### As Drupal Developers We follow [Drupal coding standards](https://www.drupal.org/docs/develop/standards) and best practices for [writing secure code](https://www.drupal.org/docs/administering-a-drupal-site/security-in-drupal/writing-secure-code-for-drupal) -- We create and maintain [secure Drupal sites](https://www.drupal.org/docs/administering-a-drupal-site/security-in-drupal) -- We understand that `alpha`, `beta` and `rc` versions are not stable and not subject to security team support. It is often preferable to run a `dev` than `alpha/beta` releases where there has been significant number of bug fixes done, and the security profile is identical. -- We periodically audit sites to determine if the set of enabled modules are up-to-date and still in use on the site. +- We create and maintain [secure Drupal sites](https://www.drupal.org/docs/administering-a-drupal-site/security-in-drupal) +- We understand that `alpha`, `beta` and `rc` versions are not stable and not subject to security team support. It is often preferable to run a `dev` than `alpha/beta` releases where there has been significant number of bug fixes done, and the security profile is identical. +- We periodically audit sites to determine if the set of enabled modules are up-to-date and still in use on the site. ### Code Creation We minimize custom code, always preferring to use community maintained modules and contribute patches when needed. -- When necessary for new functionality, we strive to create generic modules and contribute them to the parent project -- Custom code must: - - have an associated Jira (or other ticketing system) ticket - - include testing mechanisms, ideally hooked into the continuous integration pipeline - - conform to coding standards (use static code analysis where possible (such as [DCQ](https://www.drupal.org/project/dcq)) - - undergo security peer review +- When necessary for new functionality, we strive to create generic modules and contribute them to the parent project +- Custom code must: + - have an associated Jira (or other ticketing system) ticket + - include testing mechanisms, ideally hooked into the continuous integration pipeline + - conform to coding standards (use static code analysis where possible (such as [DCQ](https://www.drupal.org/project/dcq)) + - undergo security peer review The project technical lead (or a designated lead engineer/lead themer or peer-review process) is responsible for reviewing all new/modified code each sprint, and ensuring it meets a high standard of quality. @@ -54,10 +54,10 @@ Software that is not licensed under a CivicActions approved open source license We use a company identifiable email address and personally identifiable names for all company, client and service accounts: -- based on your `firstname.lastname@civicactions.com` email address -- to create multiple email addresses (that will be delivered to your main account) add a unique `+identifier` after your name -- everything after the `+` is ignored by the mailer - - e.g. `first.lastname+project-admin@civicactions.com` - - and: `first.lastname+qa1@civicactions.com` +- based on your `firstname.lastname@civicactions.com` email address +- to create multiple email addresses (that will be delivered to your main account) add a unique `+identifier` after your name -- everything after the `+` is ignored by the mailer + - e.g. `first.lastname+project-admin@civicactions.com` + - and: `first.lastname+qa1@civicactions.com` When creating test or exploratory accounts on staging or production systems, we, use a user name derived from your name, e.g., `first.lastname` or `flastname` or `flastname-admin` @@ -67,49 +67,49 @@ Privileged access to applications, websites, source code, and servers (SSH/shell Privileged account holders (Drupal, Moodle, Ilias, GNU/Linux SSH, etc.) must: -- Respect the privacy of site users, avoiding accessing personal data such as private messages -- Employ [Multi-Factor Authentication (MFA)](../../common-practices-tools/security/README.md#use-multi-factor-authentication-mfa) to ensure access is granted only to authorized personnel. +- Respect the privacy of site users, avoiding accessing personal data such as private messages +- Employ [Multi-Factor Authentication (MFA)](../../common-practices-tools/security/README.md#use-multi-factor-authentication-mfa) to ensure access is granted only to authorized personnel. ### Private keys SSH public/private key pairs are used to access CivicActions and client servers and services we use. -- RSA keys must be 2048 bits as a minimum (keys using lower strengths must be replaced). 4096 bits or higher is recommended for new keys and will soon become required. -- The private key must be protected with a passphrase that adheres to the CivicActions [Password Policy](../../company-policies/security.md#password-policy) -- Passphrases may be cached, but should expire after 1-2 hours or at the end of each login session for desktops and laptops and after 5-15 minutes for mobile devices. -- Private key files should be kept in as few places as possible, and never on external servers -- If you suspect a private key file (or its passphrase) has been compromised, [report the incident](../../common-practices-tools/security/incidents.md#reporting-an-incident) immediately. +- RSA keys must be 2048 bits as a minimum (keys using lower strengths must be replaced). 4096 bits or higher is recommended for new keys and will soon become required. +- The private key must be protected with a passphrase that adheres to the CivicActions [Password Policy](../../company-policies/security.md#password-policy) +- Passphrases may be cached, but should expire after 1-2 hours or at the end of each login session for desktops and laptops and after 5-15 minutes for mobile devices. +- Private key files should be kept in as few places as possible, and never on external servers +- If you suspect a private key file (or its passphrase) has been compromised, [report the incident](../../common-practices-tools/security/incidents.md#reporting-an-incident) immediately. ### IT Team specifics IT team system administrators working on CivicActions servers must also: -- Take the utmost caution when working on server configuration - document and test each change. -- Non-urgent yet risky changes (those with significant risk of introducing undesired side-effects) should only be made when the person expects to remain online and available for at leat two hours after the change. -- Minimize the use of root or other group accounts -- Work with the IT team to ensure server and backup health is monitored and alerts are responded to promptly. -- Ensure system backups are logically air-gapped so that they cannot be corrupted or destroyed by a bad actor. +- Take the utmost caution when working on server configuration - document and test each change. +- Non-urgent yet risky changes (those with significant risk of introducing undesired side-effects) should only be made when the person expects to remain online and available for at leat two hours after the change. +- Minimize the use of root or other group accounts +- Work with the IT team to ensure server and backup health is monitored and alerts are responded to promptly. +- Ensure system backups are logically air-gapped so that they cannot be corrupted or destroyed by a bad actor. ### Sharing Service Accounts Group accounts with shared passwords should be avoided. -- If a required service only allows a single account, LastPass password sharing or encrypted credential files can be used to share a password to a limited number of users on an "as needed" basis. -- Shared account passwords should rotate to ensure that only those users needing access continue to have access, revoking individual accounts particularly when people offboard from the project or company. +- If a required service only allows a single account, LastPass password sharing or encrypted credential files can be used to share a password to a limited number of users on an "as needed" basis. +- Shared account passwords should rotate to ensure that only those users needing access continue to have access, revoking individual accounts particularly when people offboard from the project or company. ### Incident Response -- We are trained to recognize and report [security incidents](../../common-practices-tools/security/incidents.md). -- Every project has an Incident Response Team -- We ensure that at least one member of the Incident Response Team has access to the Internet at all times. -- We train new employees and perform yearly quizzes of employees on the Incident Response procedures. -- Each project can extend or replace the default [Incident Response Plan](../../common-practices-tools/security/incident-response-plan.md). +- We are trained to recognize and report [security incidents](../../common-practices-tools/security/incidents.md). +- Every project has an Incident Response Team +- We ensure that at least one member of the Incident Response Team has access to the Internet at all times. +- We train new employees and perform yearly quizzes of employees on the Incident Response procedures. +- Each project can extend or replace the default [Incident Response Plan](../../common-practices-tools/security/incident-response-plan.md). ### Continuous Monitoring We use tools to support continuous monitoring for performance and efficiency, and to ensure proper operation and security. These tools include (not an exhaustive list): -- Event and error log capture: auditd (SELinux), fail2ban and AIDE. -- Continuous monitoring dashboards: Cloudwatch, StatusCake, OpsGenie, Splunk and New Relic. -- Automated security scanning: OpenSCAP, OWASP ZAP, and Trivy. -- Supply chain and Software Bill of Materials (SBOM): Syft and DependencyTrack. +- Event and error log capture: auditd (SELinux), fail2ban and AIDE. +- Continuous monitoring dashboards: Cloudwatch, StatusCake, OpsGenie, Splunk and New Relic. +- Automated security scanning: OpenSCAP, OWASP ZAP, and Trivy. +- Supply chain and Software Bill of Materials (SBOM): Syft and DependencyTrack. diff --git a/practice-areas/engineering/tech-lead/README.md b/practice-areas/engineering/tech-lead/README.md index 06a75e9d5b..717812f42e 100644 --- a/practice-areas/engineering/tech-lead/README.md +++ b/practice-areas/engineering/tech-lead/README.md @@ -12,20 +12,20 @@ A TL's role definition and responsibilities will vary by project. Responsibiliti ### Key -- **Responsible**: "Those who do the work to complete the task." -- **Accountable**: "The one ultimately answerable for the correct and thorough completion of the deliverable or task, the one who ensures the prerequisites of - the task are met and who delegates the work to those responsible." -- **Support**: "Helps get the task done or contributes to it". +- **Responsible**: "Those who do the work to complete the task." +- **Accountable**: "The one ultimately answerable for the correct and thorough completion of the deliverable or task, the one who ensures the prerequisites of - the task are met and who delegates the work to those responsible." +- **Support**: "Helps get the task done or contributes to it". ### Business development The TL supports: -- Reviewing RFP and appendices -- Filling out analysis documentation -- Estimating the proposed solution -- Development of project roadmaps -- High-level technical solutioning -- Requirements clarification +- Reviewing RFP and appendices +- Filling out analysis documentation +- Estimating the proposed solution +- Development of project roadmaps +- High-level technical solutioning +- Requirements clarification ### Planning @@ -33,35 +33,35 @@ The TL is responsible for release management, planning, and communication. The TL is accountable for: -- Knowing, understanding, and communicating to the team the project contract scope, expectations, boundaries, and knowledge gaps surrounding: - - project timeline - - budgets - - roles and responsibilities - - partners and supporting entities - - functional requirements - - design requirements - - accessibility requirements - - performance requirements - - security requirements - - technical landscape. -- Ensuring continuous delivery -- Leading project-wide technical discovery to understand an initiative's functional, technical, testing, security, performance, and accessibility requirements in collaboration with service design and UX discovery efforts +- Knowing, understanding, and communicating to the team the project contract scope, expectations, boundaries, and knowledge gaps surrounding: + - project timeline + - budgets + - roles and responsibilities + - partners and supporting entities + - functional requirements + - design requirements + - accessibility requirements + - performance requirements + - security requirements + - technical landscape. +- Ensuring continuous delivery +- Leading project-wide technical discovery to understand an initiative's functional, technical, testing, security, performance, and accessibility requirements in collaboration with service design and UX discovery efforts The TL supports: -- The Product Owner (PO) and Project Manager (PM) in defining development priorities and identifying high value work -- Ticket refinement -- Epic story creation -- Ticket backlog prioritization +- The Product Owner (PO) and Project Manager (PM) in defining development priorities and identifying high value work +- Ticket refinement +- Epic story creation +- Ticket backlog prioritization ### People The TL is responsible for: -- Onboarding engineers: project technical background, technical goals and active initiatives, team structure and personnel, project tools, environments, repositories, development workflows, CI/CD processes -- Offboarding engineers: removing admin access to sites/services/servers, updating any documentation, transferring tickets/knowledge, and so on -- Nurturing a project engineering team culture which values care, balance, openness, and honors client and partner culture and values (follow the platinum rule: treat others as they want to be treated). -- Fostering collaboration within and across teams and valuing listening and empathy +- Onboarding engineers: project technical background, technical goals and active initiatives, team structure and personnel, project tools, environments, repositories, development workflows, CI/CD processes +- Offboarding engineers: removing admin access to sites/services/servers, updating any documentation, transferring tickets/knowledge, and so on +- Nurturing a project engineering team culture which values care, balance, openness, and honors client and partner culture and values (follow the platinum rule: treat others as they want to be treated). +- Fostering collaboration within and across teams and valuing listening and empathy The TL is accountable for guiding all high-level technical discussions with the project team, partner teams, client, additional stakeholders, partners, and third parties. @@ -71,110 +71,110 @@ The TL supports individual professional development. The TL is accountable for: -- Triaging current and potential technical risks -- Developing and communicating risk mitigation strategies for major technical risks +- Triaging current and potential technical risks +- Developing and communicating risk mitigation strategies for major technical risks The TL supports the team: -- In gaining a broad understanding of what constitutes a risk - estimation (budget/timeline), security, performance, accessibility, usability, complexity (quality/maintenance) etc. -- In identifying, communicating, and managing risks and blockers to engineering success -- In identifying and surfacing issues around best practices +- In gaining a broad understanding of what constitutes a risk - estimation (budget/timeline), security, performance, accessibility, usability, complexity (quality/maintenance) etc. +- In identifying, communicating, and managing risks and blockers to engineering success +- In identifying and surfacing issues around best practices ### Development The TL is responsible for: -- Facilitation of implementation and release of a stable sustainable product at the end of each sprint which meets stakeholder requirements, passes quality standards (e.g. functionality, code quality, security, performance, accessibility), and conforms to established best practices -- Facilitation of establishment and implementation of development operations, processes, tools, and schedules surrounding local development, code workflows and promotion, automation, and environment usage -- Technical architecture -- Ensuring design and coding standard compliance -- Applying continuous learning within project engineering teams, CivicActions engineering team, and relevant practice areas -- Leading code review processes -- Keeping project engineering documentation thorough and current to the extent that the project can be handed off to a new engineering team -- Ensuring Agile best practices are followed within the engineering team +- Facilitation of implementation and release of a stable sustainable product at the end of each sprint which meets stakeholder requirements, passes quality standards (e.g. functionality, code quality, security, performance, accessibility), and conforms to established best practices +- Facilitation of establishment and implementation of development operations, processes, tools, and schedules surrounding local development, code workflows and promotion, automation, and environment usage +- Technical architecture +- Ensuring design and coding standard compliance +- Applying continuous learning within project engineering teams, CivicActions engineering team, and relevant practice areas +- Leading code review processes +- Keeping project engineering documentation thorough and current to the extent that the project can be handed off to a new engineering team +- Ensuring Agile best practices are followed within the engineering team The TL supports: -- Establishing and implementing continuous integration tools and processes -- Security compliance documentation +- Establishing and implementing continuous integration tools and processes +- Security compliance documentation ### Operations @todo Needs review. The TL is accountable for: -- Coordinating on-call support depending on the project -- Coordinating and delivering RCA +- Coordinating on-call support depending on the project +- Coordinating and delivering RCA The TL supports: -- Establishing and implementing site reliability, load testing, and related policy and procedures -- Disaster recovery policy and procedure +- Establishing and implementing site reliability, load testing, and related policy and procedures +- Disaster recovery policy and procedure ### Ticket work The TL is accountable for: -- Facilitating standards around implementation plans, estimates, and testing steps on tickets and holding the team accountable to these -- Ticket risk assessment +- Facilitating standards around implementation plans, estimates, and testing steps on tickets and holding the team accountable to these +- Ticket risk assessment The TL supports: -- The project team in removing ticket blockers. -- Facilitating standards around ticket creation. -- Ticket prioritization. -- Assignment of tickets when applicable. -- The Project Manager reviewing tickets for proper formatting (implementation plans, estimates, user stories) and ensures that tickets appropriately document the issue and the resolution. +- The project team in removing ticket blockers. +- Facilitating standards around ticket creation. +- Ticket prioritization. +- Assignment of tickets when applicable. +- The Project Manager reviewing tickets for proper formatting (implementation plans, estimates, user stories) and ensures that tickets appropriately document the issue and the resolution. ### Design The TL supports: -- Developing order of operations to support design and engineering collaboration -- Engineering and design teams to design technically feasible and practical solutions +- Developing order of operations to support design and engineering collaboration +- Engineering and design teams to design technically feasible and practical solutions ## Responsibilities not expected -- Knowing everything about a project: knowledge is shared among all project participants. -- Coding everything: the Tech Lead's primary responsibilities are around leading and supporting the engineering team, not the engineering itself. -- Primary organizational contact with the Product Owner: that is part of the Project Manager's role. -- Final authority on development and ticket backlog priorities: that is part of the Product Owner's role. -- Availability and support outside of established working hours, unless mutually agreed upon as a project responsibility. +- Knowing everything about a project: knowledge is shared among all project participants. +- Coding everything: the Tech Lead's primary responsibilities are around leading and supporting the engineering team, not the engineering itself. +- Primary organizational contact with the Product Owner: that is part of the Project Manager's role. +- Final authority on development and ticket backlog priorities: that is part of the Product Owner's role. +- Availability and support outside of established working hours, unless mutually agreed upon as a project responsibility. ## Skills -- Building, leading, and managing project engineering teams. -- Coaching and mentoring engineers. -- Complex problem solving. -- Risk analysis and management. -- Estimating level of effort. -- Technical prioritization. -- Managing competing priorities, parallel work streams. -- Executive functioning — organizational and planning skills applied to self and team. -- Time management for self and team. -- Communicating technical subjects to technical and non-technical audiences. -- Presenting to audiences. -- Familiar with common technical tools, their appropriate applications and strengths and weaknesses. -- Familiar with best practices of chosen technical stack. -- Relationship building. -- Conflict resolution. -- Qualities: Motivating, self-directed, bias towards action, self and team awareness, -- Values: Collaboration, listening, empathy, perseverance, resilience, adaptability, transparency, attention to detail, ownership, accountability. +- Building, leading, and managing project engineering teams. +- Coaching and mentoring engineers. +- Complex problem solving. +- Risk analysis and management. +- Estimating level of effort. +- Technical prioritization. +- Managing competing priorities, parallel work streams. +- Executive functioning — organizational and planning skills applied to self and team. +- Time management for self and team. +- Communicating technical subjects to technical and non-technical audiences. +- Presenting to audiences. +- Familiar with common technical tools, their appropriate applications and strengths and weaknesses. +- Familiar with best practices of chosen technical stack. +- Relationship building. +- Conflict resolution. +- Qualities: Motivating, self-directed, bias towards action, self and team awareness, +- Values: Collaboration, listening, empathy, perseverance, resilience, adaptability, transparency, attention to detail, ownership, accountability. ## Experience -- Gathering, defining, and translating technical requirements. -- Architecting best-of-breed technical solutions based on requirements. -- Roadmapping technical solutions. -- Implementing and continuously improving engineering processes. -- Implementing complex development tasks. -- Managing and integrating codebases on large teams. -- Reviewing code with an eye for best practices, efficiency, performance, and security. -- Testing and debugging code. -- Release management. -- Agile methodology and best practices. -- Exposure to a variety of projects of varying team sizes and durations. -- Remote-based work. +- Gathering, defining, and translating technical requirements. +- Architecting best-of-breed technical solutions based on requirements. +- Roadmapping technical solutions. +- Implementing and continuously improving engineering processes. +- Implementing complex development tasks. +- Managing and integrating codebases on large teams. +- Reviewing code with an eye for best practices, efficiency, performance, and security. +- Testing and debugging code. +- Release management. +- Agile methodology and best practices. +- Exposure to a variety of projects of varying team sizes and durations. +- Remote-based work. ## Technical leadership project roles at CivicActions @@ -196,27 +196,27 @@ The Associate Technical Lead project role is the first step for an engineer to g This is a project role, which means that: -- One individual could perform one role on one project and another role on another project (e.g. a TL on project A could also be a frontend engineer on project B). -- Multiple roles on a project could be shared by the same person (e.g. the TL could also be the Lead Engineer). This is the norm for many small and medium projects. +- One individual could perform one role on one project and another role on another project (e.g. a TL on project A could also be a frontend engineer on project B). +- Multiple roles on a project could be shared by the same person (e.g. the TL could also be the Lead Engineer). This is the norm for many small and medium projects. ### How does one become a TL? -- An individual could be hired to fulfil the project role. -- An individual could show interest and experience and volunteer for the project role. -- An individual who has experience can be asked to take on the project role. -- An individual can first step into the Associate Technical Lead project role and work towards gaining experience with the different responsibilities before they take on the TL project role. +- An individual could be hired to fulfil the project role. +- An individual could show interest and experience and volunteer for the project role. +- An individual who has experience can be asked to take on the project role. +- An individual can first step into the Associate Technical Lead project role and work towards gaining experience with the different responsibilities before they take on the TL project role. ### What are some personal OKRs that I can use to gain experience to become a TL or as an ATL? Objectives and key results (OKRs) should target various responsibilities listed above with specific key results. Examples: -- Getting involved in sales and business development. - - Completed 1-3 project scorecards. - - Participated in 1-3 project proposals. -- Leading development initiatives. - - Map out the implementation for 3-5 features end to end. - - Peer review all tickets for 3-5 epics. - - New developers are up and running within 2 business days. +- Getting involved in sales and business development. + - Completed 1-3 project scorecards. + - Participated in 1-3 project proposals. +- Leading development initiatives. + - Map out the implementation for 3-5 features end to end. + - Peer review all tickets for 3-5 epics. + - New developers are up and running within 2 business days. ### Are TLs always backend engineers at heart? What about Frontend and DevSecOps engineers? @@ -228,9 +228,9 @@ Yes. Ultimately this project role (an individual or multiple team members) is gi ## Important links for TLs -- [#engineering-techlead slack channel](https://civicactions.slack.com/archives/C017JL86MAM) (review the pinned messages). -- [Tech Lead Reading List](https://docs.google.com/spreadsheets/d/1QfK1-7IOqb7_N5451Y0FNiwvDlxirETVnl71sB_DUXE/edit#gid=0). -- [Tech Lead Call Agendas, Resources, and Notes](https://docs.google.com/document/d/1abRkMOuB9Kb2n8jlzjJnEClPCbAGOtZ6xclo6UlLiag/edit#heading=h.bsicsupyvxmj). -- [Onboarding a New Project Team Member](../../project-management/onboarding-new-project-team-member.md). +- [#engineering-techlead slack channel](https://civicactions.slack.com/archives/C017JL86MAM) (review the pinned messages). +- [Tech Lead Reading List](https://docs.google.com/spreadsheets/d/1QfK1-7IOqb7_N5451Y0FNiwvDlxirETVnl71sB_DUXE/edit#gid=0). +- [Tech Lead Call Agendas, Resources, and Notes](https://docs.google.com/document/d/1abRkMOuB9Kb2n8jlzjJnEClPCbAGOtZ6xclo6UlLiag/edit#heading=h.bsicsupyvxmj). +- [Onboarding a New Project Team Member](../../project-management/onboarding-new-project-team-member.md). diff --git a/practice-areas/engineering/text-editors-ides.md b/practice-areas/engineering/text-editors-ides.md index d6f5eb57df..b3e99a5d7c 100644 --- a/practice-areas/engineering/text-editors-ides.md +++ b/practice-areas/engineering/text-editors-ides.md @@ -8,8 +8,8 @@ We use text editors to develop code, tests, and documentation, and to manage con We use a variety of text editors and IDEs, and you are welcome to use whichever one you prefer. We do not require that you use a specific IDE or text editor, however if you need support then we strongly suggest that you use one of the editors that is commonly used by the team. -- [VSCodium](https://vscodium.com/) or [VS Code](https://code.visualstudio.com/): This is probably the most commonly used IDE on the team. It is a free, open source, cross platform editor that is available for Linux, Mac and Windows. It has a large number of extensions available, and is very configurable. Note that the official VS Code binaries do include a few closed source components (e.g. icons, marketplace integration) - VSCodium builds exclude these. For questions ask in [#engineering-vscode](https://civicactions.slack.com/messages/engineering-vscode/). -- [PHPStorm](https://www.jetbrains.com/phpstorm/) or other JetBrains IDEs: This is a commercial, closed source IDE that is available for Linux, Mac and Windows. It has a large number of features and is very configurable. It can be particular helpful if you do a lot of PHP debugging with XDebug. If you are not already a user, you could start with a free trial - if you like it and need a license [open an IT ticket](../../common-practices-tools/software-and-support/README.md) and request one. For questions ask in [#engineering-phpstorm](https://civicactions.slack.com/messages/engineering-phpstorm/). -- [Vim](http://www.vim.org/)/[Neovim](https://neovim.io/) and [Emacs](https://www.gnu.org/software/emacs/): These are free, open source, cross platform and keyboard driven text editors - or IDEs if configured more maximally, such as with [AstroNvim](https://astronvim.com/) or [Spacemacs](https://www.spacemacs.org/). They are available for Linux, Mac (typically via [Homebrew](http://brew.sh/)) and Windows (typically via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)). They are very powerful tools for text manipulation, but can have a steep learning curve - however, the skills learned can be used on both the IDEs above which have good Vim and Emacs keybindings and plugins, as well as on servers where they are often installed by default. +- [VSCodium](https://vscodium.com/) or [VS Code](https://code.visualstudio.com/): This is probably the most commonly used IDE on the team. It is a free, open source, cross platform editor that is available for Linux, Mac and Windows. It has a large number of extensions available, and is very configurable. Note that the official VS Code binaries do include a few closed source components (e.g. icons, marketplace integration) - VSCodium builds exclude these. For questions ask in [#engineering-vscode](https://civicactions.slack.com/messages/engineering-vscode/). +- [PHPStorm](https://www.jetbrains.com/phpstorm/) or other JetBrains IDEs: This is a commercial, closed source IDE that is available for Linux, Mac and Windows. It has a large number of features and is very configurable. It can be particular helpful if you do a lot of PHP debugging with XDebug. If you are not already a user, you could start with a free trial - if you like it and need a license [open an IT ticket](../../common-practices-tools/software-and-support/README.md) and request one. For questions ask in [#engineering-phpstorm](https://civicactions.slack.com/messages/engineering-phpstorm/). +- [Vim](http://www.vim.org/)/[Neovim](https://neovim.io/) and [Emacs](https://www.gnu.org/software/emacs/): These are free, open source, cross platform and keyboard driven text editors - or IDEs if configured more maximally, such as with [AstroNvim](https://astronvim.com/) or [Spacemacs](https://www.spacemacs.org/). They are available for Linux, Mac (typically via [Homebrew](http://brew.sh/)) and Windows (typically via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)). They are very powerful tools for text manipulation, but can have a steep learning curve - however, the skills learned can be used on both the IDEs above which have good Vim and Emacs keybindings and plugins, as well as on servers where they are often installed by default. If you still have questions, ask in Slack: [#engineering](https://civicactions.slack.com/messages/engineering/) diff --git a/practice-areas/help-desk/project-support-accessibility-guidelines.md b/practice-areas/help-desk/project-support-accessibility-guidelines.md index 6826eb97be..cbd5ff8ff1 100644 --- a/practice-areas/help-desk/project-support-accessibility-guidelines.md +++ b/practice-areas/help-desk/project-support-accessibility-guidelines.md @@ -8,9 +8,9 @@ title: Accessibility guidelines The CivicActions Support practice area is committed to following the guidance provided in the [Americans with Disabilities Act](https://www.ada.gov/) and following the best practices for inclusive customer service such as the [AODA Accessibility for Ontarians with Disabilities Act](https://www.ontario.ca/laws/statute/05a11). CivicActions is committed to providing a barrier-free environment for its customers, clients, and staff and to providing our support in a manner that respects the dignity and independence of people with disabilities. -- [CivicActions Accessibility Pledge](https://accessibility.civicactions.com/posts/CivicActions-Accessibility-Pledge) -- [CivicActions Accessibility Statement](https://civicactions.com/accessibility-statement) -- [CivicActions Accessibility Website](https://accessibility.civicactions.com) +- [CivicActions Accessibility Pledge](https://accessibility.civicactions.com/posts/CivicActions-Accessibility-Pledge) +- [CivicActions Accessibility Statement](https://civicactions.com/accessibility-statement) +- [CivicActions Accessibility Website](https://accessibility.civicactions.com) ## Organizational scope @@ -20,8 +20,8 @@ This guidance applies to every person who provides support to members of the pub The standards, rules, and guidelines on providing accessible customer service are set out in the: -- [Accessibility Standards for Customer Service (Ontario Regulation 429/07)](https://www.ontario.ca/laws/regulation/r07429) -- [ADA Requirements: Effective Communication](https://www.ada.gov/resources/effective-communication/) +- [Accessibility Standards for Customer Service (Ontario Regulation 429/07)](https://www.ontario.ca/laws/regulation/r07429) +- [ADA Requirements: Effective Communication](https://www.ada.gov/resources/effective-communication/) As standards, rules, and guidelines develop, the CivicActions Support practice area will continue to consult with Subject-Matter Experts (SMEs) and General Counsel to ensure our policies are current, reflective of global needs, and implemented company-wide. @@ -37,9 +37,9 @@ Our goal at CivicActions is to achieve or exceed the latest [Web Content Accessi Communication is provided in a way that is consistent with the core principles of independence, dignity, integration, and equality of opportunity. For more information, please refer to the following links: -- [CivicActions Guidebook](../accessibility/README.md) -- [CivicActions Accessibility Website](https://accessibility.civicactions.com) -- [Web Content Accessibility Guidelines (WCAG) 2 Overview](https://www.w3.org/WAI/standards-guidelines/wcag) +- [CivicActions Guidebook](../accessibility/README.md) +- [CivicActions Accessibility Website](https://accessibility.civicactions.com) +- [Web Content Accessibility Guidelines (WCAG) 2 Overview](https://www.w3.org/WAI/standards-guidelines/wcag) ## Customer feedback diff --git a/practice-areas/help-desk/project-support-checklist.md b/practice-areas/help-desk/project-support-checklist.md index a479fdb795..90f98eab9f 100644 --- a/practice-areas/help-desk/project-support-checklist.md +++ b/practice-areas/help-desk/project-support-checklist.md @@ -6,26 +6,26 @@ title: Support checklist ## 1/ Start by defining "support" for your project team -- What does support or O&M mean for your team? -- What is included in your service? +- What does support or O&M mean for your team? +- What is included in your service? Make these a part of your core operating tenets and include it in your project [TWA](../project-management/team-working-agreements-instructions.md). Make sure everyone on the project understands this definition. ## 2/ Define roles and responsibilities for support providers -- The primary goal of support is to respond to questions and solve issues for our customers, end users, stakeholders and clients who are using a product or service (which may be provided or managed by CivicActions). -- The secondary goal is to support the team by allowing for retention of focus in competency areas. Therefore everyone needs to know the breakdown of responsibilities for team members. Are there specialties? Tiers? How about schedules? Everyone on the team needs to understand these details. +- The primary goal of support is to respond to questions and solve issues for our customers, end users, stakeholders and clients who are using a product or service (which may be provided or managed by CivicActions). +- The secondary goal is to support the team by allowing for retention of focus in competency areas. Therefore everyone needs to know the breakdown of responsibilities for team members. Are there specialties? Tiers? How about schedules? Everyone on the team needs to understand these details. ## 3/ Define your support (O&M) workflow and tasks Next define the workflow for support, including all associated tasks. Document - even in the simplest form - your workflow and share it with the team. -- If possible, have a single point of entry to receive, respond to, and track support requests -- Create a new ticket for each support request -- Create documentation for support processes as well as solutions for support related issues -- Documentation can include canned answers, knowledge base, frequently asked questions, common problems, etc. -- FAQs and knowledge base articles can often be turned into a self-service support portal for end users and stakeholders -- Documentation should be stored in a central location accessible to all team members +- If possible, have a single point of entry to receive, respond to, and track support requests +- Create a new ticket for each support request +- Create documentation for support processes as well as solutions for support related issues +- Documentation can include canned answers, knowledge base, frequently asked questions, common problems, etc. +- FAQs and knowledge base articles can often be turned into a self-service support portal for end users and stakeholders +- Documentation should be stored in a central location accessible to all team members ## 4/ Know your Service Level Agreements (SLAs) @@ -80,26 +80,26 @@ Often support responses are broken by severity levels, i.e., P1, P2, etc. Confir ## 5/ If possible, automate your tooling -- Automate as many support related processes as possible -- Automate manual or low-lift tasks in order to free up effort for more complex tasks -- Look for apps, plugins, and integrations that can improve support efficiency -- Check for existing resources or documentation that can be refined and made available for broader use +- Automate as many support related processes as possible +- Automate manual or low-lift tasks in order to free up effort for more complex tasks +- Look for apps, plugins, and integrations that can improve support efficiency +- Check for existing resources or documentation that can be refined and made available for broader use ## 6/ Arrange for backup for your Support resources -- Determine the process for when primary support team members are out of office -- Ensure backup support providers have proper access/privileges to necessary accounts -- Share documentation among team members -- Provide training for all team members +- Determine the process for when primary support team members are out of office +- Ensure backup support providers have proper access/privileges to necessary accounts +- Share documentation among team members +- Provide training for all team members ## 7/ Creating accessible content When designing content for project support, be sure to weave accessibility best practices into it. Some helpful tips: -- Include ALT text for applicable images -- Confirm plain language -- Avoid .pdf documents and instead - whenever possible - use a responsive layout that allows for resizing -- Use headings and subheadings -- Provide captions and transcripts for videos -- Ensure keyboard navigation -- Test for accessibility +- Include ALT text for applicable images +- Confirm plain language +- Avoid .pdf documents and instead - whenever possible - use a responsive layout that allows for resizing +- Use headings and subheadings +- Provide captions and transcripts for videos +- Ensure keyboard navigation +- Test for accessibility diff --git a/practice-areas/project-management/README.md b/practice-areas/project-management/README.md index 448189ed7d..bd5cc8bca8 100644 --- a/practice-areas/project-management/README.md +++ b/practice-areas/project-management/README.md @@ -6,10 +6,10 @@ title: Project Manager role Project Managers envelop the unique opportunity to hold a project on task and budget, which is paramount, yet also to include: -- accessibility best practices at every stage; -- be a role model for effective communication; -- support and enable innovation; -- and also remove impediments so that our development benefits the public. +- accessibility best practices at every stage; +- be a role model for effective communication; +- support and enable innovation; +- and also remove impediments so that our development benefits the public. ## The difference between the Project Manager and Scrum Master roles @@ -23,35 +23,35 @@ This pages serves to define the Project Manager role in Agile ceremonies. [Also ### Primary Responsibilities -- Taking and distributing notes (if the team supports this method)([scrum note template](https://docs.google.com/document/d/17tl3lPu-3Uo6_YCEtb6AH9HsaILLS1UTmoUFIuXoqDc/edit)) -- Timebox monitoring for team calls -- Sticking to the scrum process, or holding the team accountable to after-meeting topics -- Keeping the team abreast on all important events (e.g., deployments, due dates, blockers, etc.) +- Taking and distributing notes (if the team supports this method)([scrum note template](https://docs.google.com/document/d/17tl3lPu-3Uo6_YCEtb6AH9HsaILLS1UTmoUFIuXoqDc/edit)) +- Timebox monitoring for team calls +- Sticking to the scrum process, or holding the team accountable to after-meeting topics +- Keeping the team abreast on all important events (e.g., deployments, due dates, blockers, etc.) ### Other tasks -- Paying attention to balance scores -- Reminding the team about expectations for forthcoming ceremonies (e.g., the Review) -- Tackling all impediments raised -- Sending meeting invites as required +- Paying attention to balance scores +- Reminding the team about expectations for forthcoming ceremonies (e.g., the Review) +- Tackling all impediments raised +- Sending meeting invites as required ## Sprint Review/ Demo ### What is a Review? -- A great ceremony to provide an informal demo from the Project Team (the entire Dev Team, including UX, Design, Developers, DevOps) to show their work -- The work may still be in progress -- It is an opportunity to focus on user value and to garner feedback from the Product Owner and all stakeholder groups in real time +- A great ceremony to provide an informal demo from the Project Team (the entire Dev Team, including UX, Design, Developers, DevOps) to show their work +- The work may still be in progress +- It is an opportunity to focus on user value and to garner feedback from the Product Owner and all stakeholder groups in real time **Responsibilities** -- The Project Manager's role is to be a facilitator -- Recording the call, if possible, is positive -- Support the team by providing details about the Review prior (e.g., who is showing which tickets). -- Always give your team preparation time, reinforcing the need to speak to user value -- The Project Manager starts the call and explains the agenda, purpose, timebox, and any processes changes from the last call -- Notes, especially those made transparent, are encouraged -- Any subsequent actions (i.e., new tickets, discovery calls, etc.) are under the purview of the Project Manager +- The Project Manager's role is to be a facilitator +- Recording the call, if possible, is positive +- Support the team by providing details about the Review prior (e.g., who is showing which tickets). +- Always give your team preparation time, reinforcing the need to speak to user value +- The Project Manager starts the call and explains the agenda, purpose, timebox, and any processes changes from the last call +- Notes, especially those made transparent, are encouraged +- Any subsequent actions (i.e., new tickets, discovery calls, etc.) are under the purview of the Project Manager ## Retrospective @@ -59,17 +59,17 @@ Retrospectives are imperative for a trusting, self-sustaining and innovative tea **Responsibilities** -- Scheduling -- Facilitating -- Keeping to the timebox -- Ensuring all voices are heard -- Documenting the outcomes -- Helping the team keep and meet their commitments +- Scheduling +- Facilitating +- Keeping to the timebox +- Ensuring all voices are heard +- Documenting the outcomes +- Helping the team keep and meet their commitments ### Resources -- Check out this retrospective template: [TEMPLATE: Sprint Retrospective (Basic)](https://trello.com/b/YEXXigXH/template-sprint-retrospective) -- And this one also: [TEMPLATE: Sprint Retrospective(Grouping Issues)](https://trello.com/b/jG9U4I6l/template-sprint-retrospective-grouping-issues) +- Check out this retrospective template: [TEMPLATE: Sprint Retrospective (Basic)](https://trello.com/b/YEXXigXH/template-sprint-retrospective) +- And this one also: [TEMPLATE: Sprint Retrospective(Grouping Issues)](https://trello.com/b/jG9U4I6l/template-sprint-retrospective-grouping-issues) ## Refinement @@ -77,11 +77,11 @@ Refinement calls are an important manner for the DevTeam to connect directly wit **Responsibilities** -- Coordinating with the Product Manager, share suggetions with the Product Owner and DevTeam prior, including a list of tickets and from whom answers will be most appropriate -- Share your screen to review the backlog -- Start with any security-related tickets -- Confirm that all tickets include a user story, story points, technical details, any dependencies and also acceptance criteria -- Ensure the Product Owner and DevTeam have identified the highest priority tasks for both the forthcoming sprint and also the quarter/PI +- Coordinating with the Product Manager, share suggetions with the Product Owner and DevTeam prior, including a list of tickets and from whom answers will be most appropriate +- Share your screen to review the backlog +- Start with any security-related tickets +- Confirm that all tickets include a user story, story points, technical details, any dependencies and also acceptance criteria +- Ensure the Product Owner and DevTeam have identified the highest priority tasks for both the forthcoming sprint and also the quarter/PI NOTE: A helpful video example: @@ -91,50 +91,50 @@ Sprint Planning is an excellent moment to confirm DevTeam velociy expectations, **Responsibilities** -- Coordinating with the Product Manager, share tickets prior to the call -- Confirm the work load per DevTeam member -- Allow an open space for questions and concerns -- Ask the team and Product Owner to call out any risk -- Verify that assignments, per DevTeam member, are on target -- Verify that Product Owner priorities are met -- Reinforce the goal of the sprint +- Coordinating with the Product Manager, share tickets prior to the call +- Confirm the work load per DevTeam member +- Allow an open space for questions and concerns +- Ask the team and Product Owner to call out any risk +- Verify that assignments, per DevTeam member, are on target +- Verify that Product Owner priorities are met +- Reinforce the goal of the sprint ## Any other meetings Other ways that the Project Manager supports the team includes, yet is not limited to, the following: -- Setting Team Working Agreements (TWAs) -- Reviewing QASP metrics -- Confirming all deliverables are being met, including those of DevOps -- Talking about workflow -- Decisions from a Retrospective -- Assessing UAT -- etc. +- Setting Team Working Agreements (TWAs) +- Reviewing QASP metrics +- Confirming all deliverables are being met, including those of DevOps +- Talking about workflow +- Decisions from a Retrospective +- Assessing UAT +- etc. During these types of meetings the Project Manager again serves as facilitator: -- Scheduling -- Confirming all participants have a voice -- Respecting the team's time by staying within the timebox -- Making the meeting notes transparent -- Supporting the team with reminders on deadlnes, big picture connections, etc. -- Ensure there is ownership for each action item -- Create any tickets or documents necessary +- Scheduling +- Confirming all participants have a voice +- Respecting the team's time by staying within the timebox +- Making the meeting notes transparent +- Supporting the team with reminders on deadlnes, big picture connections, etc. +- Ensure there is ownership for each action item +- Create any tickets or documents necessary ## Summary of Project Manager responsibilities -- To build a self-sustaining team that delivers best-of-class work and also has fun -- To enable the team to develop applications that support all users -- To document absolutely everything -- To handle pragmatics (e.g., scheduling, notes, etc.) -- Approving OOO requests -- Status and deliverable reporting (schedule, budget) -- Verifying QASP metrics -- Onboarding new team members -- Coordinating contractors -- Participating in QA -- Creating a conducive space for innovation -- Modeling healthy communication patterns -- Modeling healthy work / life balance -- Asking questions from the user perspective and including, on all calls, the voice of the user -- Empowering the team +- To build a self-sustaining team that delivers best-of-class work and also has fun +- To enable the team to develop applications that support all users +- To document absolutely everything +- To handle pragmatics (e.g., scheduling, notes, etc.) +- Approving OOO requests +- Status and deliverable reporting (schedule, budget) +- Verifying QASP metrics +- Onboarding new team members +- Coordinating contractors +- Participating in QA +- Creating a conducive space for innovation +- Modeling healthy communication patterns +- Modeling healthy work / life balance +- Asking questions from the user perspective and including, on all calls, the voice of the user +- Empowering the team diff --git a/practice-areas/project-management/contractual-requirements.md b/practice-areas/project-management/contractual-requirements.md index 5e1a091bfe..74a8c4bad7 100644 --- a/practice-areas/project-management/contractual-requirements.md +++ b/practice-areas/project-management/contractual-requirements.md @@ -8,14 +8,14 @@ The project manager is the main team member responsible for ensuring the team st The PM should have a method for tracking these deliverables (such as a spreadsheet in the client project folder) that includes (but is not limited to) the following: -- Task ID number (such as PWS number from the contract) -- Deliverable name -- Deliverable description -- Due date -- Status of deliverable (to do, in progress, ongoing monthly, delivered, accepted) -- Submission date of deliverable -- Link to Jira ticket (if applicable) -- Deliverable owner/lead (if applicable) -- Cost associated with deliverable (if applicable) +- Task ID number (such as PWS number from the contract) +- Deliverable name +- Deliverable description +- Due date +- Status of deliverable (to do, in progress, ongoing monthly, delivered, accepted) +- Submission date of deliverable +- Link to Jira ticket (if applicable) +- Deliverable owner/lead (if applicable) +- Cost associated with deliverable (if applicable) [Example template for tracking deliverables](https://docs.google.com/spreadsheets/d/1pgLJIIPs9axqpIy_Ye3swqIeE3Nehx-vTq7pGKASIPQ/edit#gid=0) diff --git a/practice-areas/project-management/general-tooling-guidelines-for-project-teams.md b/practice-areas/project-management/general-tooling-guidelines-for-project-teams.md index 4a0cb541eb..91876516fa 100644 --- a/practice-areas/project-management/general-tooling-guidelines-for-project-teams.md +++ b/practice-areas/project-management/general-tooling-guidelines-for-project-teams.md @@ -6,28 +6,28 @@ title: Guidelines for project tools ## Slack -- We use Slack for casual and/or working chats -- Slack communications are often asynchronous -- To notify someone in particular, type @name with your message -- If you want to call attention to everyone subscribed to channel, write @channel -- To alert only those in a channel or group who are online, write @here -- We default to open, so when in doubt, message the group in the channel (#client-project-name) instead of a direct message -- CivicActions can download archival Slack messages if needed -- The expected response time for Slack messages is 2-3 hours during working days -- Use threading in Slack to keep conversations concise and clear +- We use Slack for casual and/or working chats +- Slack communications are often asynchronous +- To notify someone in particular, type @name with your message +- If you want to call attention to everyone subscribed to channel, write @channel +- To alert only those in a channel or group who are online, write @here +- We default to open, so when in doubt, message the group in the channel (#client-project-name) instead of a direct message +- CivicActions can download archival Slack messages if needed +- The expected response time for Slack messages is 2-3 hours during working days +- Use threading in Slack to keep conversations concise and clear ## Email -- We prefer Slack over email - generally email is used for communicating with people who are not on Slack, for sending formal deliverables, etc. -- We use a list (client@civicactions.com) for emails; this list includes everyone on the team (as well as some additional stakeholders and support staff) -- We recommend keeping emails transparent to the team, e.g., anything that applies to everyone -- State the name of the person or persons that need to pay attention to email: NAME: Subject or ALL: Subject -- CivicActions team members might include a signature that indicates we are contractors to the given organization -- The expected response time for email messages is within 24 hours +- We prefer Slack over email - generally email is used for communicating with people who are not on Slack, for sending formal deliverables, etc. +- We use a list (client@civicactions.com) for emails; this list includes everyone on the team (as well as some additional stakeholders and support staff) +- We recommend keeping emails transparent to the team, e.g., anything that applies to everyone +- State the name of the person or persons that need to pay attention to email: NAME: Subject or ALL: Subject +- CivicActions team members might include a signature that indicates we are contractors to the given organization +- The expected response time for email messages is within 24 hours ## Jira -- We track all work (current and planned) in Jira or an equivalent -- If we are discussing something that needs to be done and there isn't already a Jira ticket, we will create one -- If we are discussing something in Slack or on a call that does relate to a ticket, we make sure the conversation is recorded in the ticket (even if it's only a copy-paste of the Slack chat) -- We ensure that tickets are up to date - tickets being actively worked on at least daily (normally more) and doing a pass through all other assigned tickets 2 or 3 times a week +- We track all work (current and planned) in Jira or an equivalent +- If we are discussing something that needs to be done and there isn't already a Jira ticket, we will create one +- If we are discussing something in Slack or on a call that does relate to a ticket, we make sure the conversation is recorded in the ticket (even if it's only a copy-paste of the Slack chat) +- We ensure that tickets are up to date - tickets being actively worked on at least daily (normally more) and doing a pass through all other assigned tickets 2 or 3 times a week diff --git a/practice-areas/project-management/growth-mindset.md b/practice-areas/project-management/growth-mindset.md index 4d83b804be..0a8f7117b4 100644 --- a/practice-areas/project-management/growth-mindset.md +++ b/practice-areas/project-management/growth-mindset.md @@ -20,13 +20,13 @@ Definition from Carol Dweck: When students believe they can get smarter, they un ## Why? -- We work at a rapid pace and under tight deadlines -- At times we will trip over each other +- We work at a rapid pace and under tight deadlines +- At times we will trip over each other If we think of giving and receiving feedback to other team members in terms of -- Role -- The project as a whole +- Role +- The project as a whole Then we may embrace a growth mindset, or the idea that team improvement happens at the individual level and only via effective iterations. @@ -34,27 +34,27 @@ Then we may embrace a growth mindset, or the idea that team improvement happens ### Give Feedback -- Focus on the project first, and the role second -- Ask permission to give feedback, confirming that the recipient is willing to absorb it -- Use the phrase, "It would be better for me if…" (again focusing on your role and that of the other person) -- Stop talking and listen +- Focus on the project first, and the role second +- Ask permission to give feedback, confirming that the recipient is willing to absorb it +- Use the phrase, "It would be better for me if…" (again focusing on your role and that of the other person) +- Stop talking and listen Remember: -- Feedback is founded on confidentiality and trust -- It is critical to confirm the timing for the feedback to be received -- The solution lies within the recipient +- Feedback is founded on confidentiality and trust +- It is critical to confirm the timing for the feedback to be received +- The solution lies within the recipient ### Receive Feedback -- Listen and Be Present -- Demonstrate active Listening -- Maintain eye contact -- Be mindful of posture -- Hear it from the place of being role- and project-based -- Hear it from the place of the person trusting you enough to share it -- Ask a clarifying question. For example, "Would it help if I ...?" +- Listen and Be Present +- Demonstrate active Listening +- Maintain eye contact +- Be mindful of posture +- Hear it from the place of being role- and project-based +- Hear it from the place of the person trusting you enough to share it +- Ask a clarifying question. For example, "Would it help if I ...?" Remember: -- The person telling you is working to improve the team; they care about your success +- The person telling you is working to improve the team; they care about your success diff --git a/practice-areas/project-management/innovation.md b/practice-areas/project-management/innovation.md index 40585e2a78..8b7996a1b3 100644 --- a/practice-areas/project-management/innovation.md +++ b/practice-areas/project-management/innovation.md @@ -8,26 +8,26 @@ Innovation is a key component to CivicActions work. We are committed to bringing ## Challenge Overview -- We aspire to confirm that all innovative ideas are heard, acknowledged, and that the contributor is made aware of next steps (and that we have the capacity to follow-up on the needed action items) -- We work to ensure we are equipped to move forward on innovative ideas, in order to demonstrate we are hearing (and acting on) team suggestions and to avoid creating a "graveyard of good ideas" paradigm +- We aspire to confirm that all innovative ideas are heard, acknowledged, and that the contributor is made aware of next steps (and that we have the capacity to follow-up on the needed action items) +- We work to ensure we are equipped to move forward on innovative ideas, in order to demonstrate we are hearing (and acting on) team suggestions and to avoid creating a "graveyard of good ideas" paradigm ## Objectives -- We encourage ideas to be "bigger" than a given sprint or retro, and welcome all input, motivating/coaching team members to think "big picture" -- We allow innovative ideas to be shared (and captured) across the entire project (all teams) -- We create a simplified means of assessing Level of Effort (LOE), Return On Investment (ROI), etc., so we may adequately prioritize potential work -- We ensure there is an easy way to view the status of ideas and to parse themes -- And we formally incorporate this process into [Team Working Agreements (TWAs)](team-working-agreements-instructions.md) +- We encourage ideas to be "bigger" than a given sprint or retro, and welcome all input, motivating/coaching team members to think "big picture" +- We allow innovative ideas to be shared (and captured) across the entire project (all teams) +- We create a simplified means of assessing Level of Effort (LOE), Return On Investment (ROI), etc., so we may adequately prioritize potential work +- We ensure there is an easy way to view the status of ideas and to parse themes +- And we formally incorporate this process into [Team Working Agreements (TWAs)](team-working-agreements-instructions.md) ## Phase one - MVP process (aka starting simple) -- Begin by leveraging existing team retros, working with ScrumMasters -- Create tickets in Jira (or another medium) for innovative ideas -- Tickets should be tagged in a certain, yet consistent, manner (e.g., specific labels, components, issue type, etc.) -- Establish a custom, program-level board for tracking (or incorporate the innovation tickets into the existing backlog) -- Handoff ticket(s) to the Technical Lead (or another fitting role) for review during project leadership calls -- Request that the Technical Lead determine feasibility, LOE, ROI, etc., around the concept (and also noting feedback in the ticket, for transparency) -- Plan next steps and potentially schedule work where appropriate +- Begin by leveraging existing team retros, working with ScrumMasters +- Create tickets in Jira (or another medium) for innovative ideas +- Tickets should be tagged in a certain, yet consistent, manner (e.g., specific labels, components, issue type, etc.) +- Establish a custom, program-level board for tracking (or incorporate the innovation tickets into the existing backlog) +- Handoff ticket(s) to the Technical Lead (or another fitting role) for review during project leadership calls +- Request that the Technical Lead determine feasibility, LOE, ROI, etc., around the concept (and also noting feedback in the ticket, for transparency) +- Plan next steps and potentially schedule work where appropriate ## One more thought diff --git a/practice-areas/project-management/leave-requests-and-stepping-away.md b/practice-areas/project-management/leave-requests-and-stepping-away.md index 40fb7bd030..d96007d70a 100644 --- a/practice-areas/project-management/leave-requests-and-stepping-away.md +++ b/practice-areas/project-management/leave-requests-and-stepping-away.md @@ -16,9 +16,9 @@ All Team members are asked to complete the following when requesting OOO leave: 4. Confirm that your OOO is placed on any team calendar(s), plus the CivicActions OOO calendar 5. Remind your teammates about your OOO: -- At Sprint Planning -- Prior to sprint turnover -- At least three days in advance (and longer for extended time off) +- At Sprint Planning +- Prior to sprint turnover +- At least three days in advance (and longer for extended time off) ## Unexpected Event Process diff --git a/practice-areas/project-management/listserv-setup.md b/practice-areas/project-management/listserv-setup.md index 1e0e2ded0e..70c4460a8e 100644 --- a/practice-areas/project-management/listserv-setup.md +++ b/practice-areas/project-management/listserv-setup.md @@ -10,28 +10,28 @@ We use internal and client-facing listservs for email communication. Project Man ## Naming conventions -- (includes clients) -- (just for CivicActions staff) +- (includes clients) +- (just for CivicActions staff) ## Create a new project email list -- You need to be logged in using your civicactions.com email address -- [Create a group](https://groups.google.com/a/civicactions.net/forum/#!creategroup) -- Leave the defaults, usually (read the options on that page, it's pretty self-explanatory) +- You need to be logged in using your civicactions.com email address +- [Create a group](https://groups.google.com/a/civicactions.net/forum/#!creategroup) +- Leave the defaults, usually (read the options on that page, it's pretty self-explanatory) ## Before adding users -- Under Basic Permissions: Check off "Allow new users not in civicactions". -- Under Posting Permissions: For the Post field select all options including "Anyone on the web" so that clients can email to the list and the list can be CC'd on other's emails. -- Under Email Options: Add \[subject prefix] that will show up in all emails in the subject line -- Under Email Options: Set "Post replies" "To the entire group" (in most cases) -- Under Email Options: You can set auto-replies, custom footers, etc. -- There are lots of other settings under other menu items. +- Under Basic Permissions: Check off "Allow new users not in civicactions". +- Under Posting Permissions: For the Post field select all options including "Anyone on the web" so that clients can email to the list and the list can be CC'd on other's emails. +- Under Email Options: Add \[subject prefix] that will show up in all emails in the subject line +- Under Email Options: Set "Post replies" "To the entire group" (in most cases) +- Under Email Options: You can set auto-replies, custom footers, etc. +- There are lots of other settings under other menu items. ## Adding users -- In most cases, you'll want to use "Direct add members" instead of "Invite members", so that invitees don't need to take any action. -- You can set a welcome message that should be sticky for future members that get added. -- Add and to every list you create. +- In most cases, you'll want to use "Direct add members" instead of "Invite members", so that invitees don't need to take any action. +- You can set a welcome message that should be sticky for future members that get added. +- Add and to every list you create. ![alt text](../../assets/images/create-google-group-listserv.png "PM listserv setup") diff --git a/practice-areas/project-management/mods-and-extensions.md b/practice-areas/project-management/mods-and-extensions.md index 555649e674..6072fc3f05 100644 --- a/practice-areas/project-management/mods-and-extensions.md +++ b/practice-areas/project-management/mods-and-extensions.md @@ -48,10 +48,10 @@ Any type of contractual change is also a good time to review resourcing, especia ## Preparing for a Mod -- Start with a short summary document which outlines the following: - - Why the change is required - - The current contractual language - - The proposed contractual language (e.g., from old paragraphs, page numbers, etc. to replacement language matched to old paragraphs, page numbers, etc.) -- Schedule an internal call to review -- Work with Legal and Sales to confirm initial strategy (high-level overview of new objectives, staffing proposal, and pricing) -- Work with the Project Team leads to craft a work plan (here is a sample document) that reflects the proposed new objectives, staffing and pricing. +- Start with a short summary document which outlines the following: + - Why the change is required + - The current contractual language + - The proposed contractual language (e.g., from old paragraphs, page numbers, etc. to replacement language matched to old paragraphs, page numbers, etc.) +- Schedule an internal call to review +- Work with Legal and Sales to confirm initial strategy (high-level overview of new objectives, staffing proposal, and pricing) +- Work with the Project Team leads to craft a work plan (here is a sample document) that reflects the proposed new objectives, staffing and pricing. diff --git a/practice-areas/project-management/onboarding-new-project-team-member.md b/practice-areas/project-management/onboarding-new-project-team-member.md index 95cfdf3022..ca2629da50 100644 --- a/practice-areas/project-management/onboarding-new-project-team-member.md +++ b/practice-areas/project-management/onboarding-new-project-team-member.md @@ -6,23 +6,23 @@ title: Onboarding Onboarding a new team member - to a project team - is a great opportunity for the Project Manager to confirm all project materials are in good standing. Some suggestions are as follows: -- The Project Manager will update the project Onboarding Deck/Brief, adding the new colleague, plus verifying all details are accurate -- The Project Manager will coordinate with People Ops about the official start date, expecting that the first fours days, at least, will be devoted to company onboarding (whether CivicActions or a partner) -- The Project Manager and Tech Lead, plus any other applicable colleagues, shall meet with the new team member before they begin. The objective is to discuss the project and set expectations -
Note: If the new team member is a contractor, the interview will focus on fit for team and work capabilities -- Following the call, the Project Manager is encouraged to write a follow up email outlining what was discussed; providing links; sharing helpful screenshots; providing next steps, etc. -- The Project Manager creates a ticket to track the onboarding process / progress for the new team member. The ticket will include - yet is not limited to - the following: -
A/ Granting account access -
B/ Discussing time tracking (with examples) -
C/ Getting an SSH key -
D/ The project Onboarding Brief -
E/ Explaining balance scores -
F/ Highlighting applicable scope -
G/ Invitations to email lists -
H/ Access to tools like Slack, Jira, etc. -- The Project Manager shall do a JIRA workflow walkthrough, highlighting the ticket management processes; acceptance criteria; QA steps, etc. -- The Project Manager adds the person to Plans and Assignments in Unanet -- The Project Manager adds the new team member to the appropriate Google Drives -- If the project requires any type of background check, fingerprinting, security training courses, etc., the Project Manager is responsible for ensuring timely completion of these tasks. If possible, add details to the ticket for tracking -- If the contract requires adjustment, e.g., key personnel, for the new team member, the Project Manager will lead this effort (asking for help from management if needed) -- If the new team member is a contractor, the Project Manager shall prepare an "Offboard Card" to ensure the contractor is properly removed from CivicActions tools, files, and project lists after their work is complete. See [offboard card template](https://trello.com/c/sXpzezNI/60-offboard-template) and [Offboarding a Contractor from a Project](project-offboarding.md) +- The Project Manager will update the project Onboarding Deck/Brief, adding the new colleague, plus verifying all details are accurate +- The Project Manager will coordinate with People Ops about the official start date, expecting that the first fours days, at least, will be devoted to company onboarding (whether CivicActions or a partner) +- The Project Manager and Tech Lead, plus any other applicable colleagues, shall meet with the new team member before they begin. The objective is to discuss the project and set expectations +
Note: If the new team member is a contractor, the interview will focus on fit for team and work capabilities +- Following the call, the Project Manager is encouraged to write a follow up email outlining what was discussed; providing links; sharing helpful screenshots; providing next steps, etc. +- The Project Manager creates a ticket to track the onboarding process / progress for the new team member. The ticket will include - yet is not limited to - the following: +
A/ Granting account access +
B/ Discussing time tracking (with examples) +
C/ Getting an SSH key +
D/ The project Onboarding Brief +
E/ Explaining balance scores +
F/ Highlighting applicable scope +
G/ Invitations to email lists +
H/ Access to tools like Slack, Jira, etc. +- The Project Manager shall do a JIRA workflow walkthrough, highlighting the ticket management processes; acceptance criteria; QA steps, etc. +- The Project Manager adds the person to Plans and Assignments in Unanet +- The Project Manager adds the new team member to the appropriate Google Drives +- If the project requires any type of background check, fingerprinting, security training courses, etc., the Project Manager is responsible for ensuring timely completion of these tasks. If possible, add details to the ticket for tracking +- If the contract requires adjustment, e.g., key personnel, for the new team member, the Project Manager will lead this effort (asking for help from management if needed) +- If the new team member is a contractor, the Project Manager shall prepare an "Offboard Card" to ensure the contractor is properly removed from CivicActions tools, files, and project lists after their work is complete. See [offboard card template](https://trello.com/c/sXpzezNI/60-offboard-template) and [Offboarding a Contractor from a Project](project-offboarding.md) diff --git a/practice-areas/project-management/planning-onsite-meetings.md b/practice-areas/project-management/planning-onsite-meetings.md index 1b4b4be81a..8fc8227a48 100644 --- a/practice-areas/project-management/planning-onsite-meetings.md +++ b/practice-areas/project-management/planning-onsite-meetings.md @@ -8,11 +8,11 @@ We sometimes meet with clients "onsite" (or in their office) to conduct discover ## Onsite Planning Guidelines -- Create a Trello board for all the details: lodging, meals, transportation, prep tasks, etc. See [TEMPLATE: Onsite Meeting Planning](https://trello.com/b/bAaDzP0s/template-onsite-meeting-planning) -- Create a budget and check the contract for allowed amount. Then get approval from management if out-of-pocket budget is required -
[TEMPLATE: Onsite Travel Estimates](https://docs.google.com/spreadsheets/d/1dMNIFuhIeDMtqyp5oYpsLrXO9CVRZ-5ooPoR54doW7U/edit?usp=drive_web&ouid=103893616702532363241) -- Create invites on the project calendar for the onsite meetings and included participants -- Research hotels and coordinate booking details with our lead accountant -- Remind CivicActions participants to coordinate flights with our lead accountant -- Research meal options and coordinate with our lead accountant on food orders, delivery, and reservations -- [TEMPLATE: Discovery](https://trello.com/b/TtMYHp1i/template-discovery) includes a backlog of potential onsite discovery activities and may be useful if your onsite meetings are discovery-related +- Create a Trello board for all the details: lodging, meals, transportation, prep tasks, etc. See [TEMPLATE: Onsite Meeting Planning](https://trello.com/b/bAaDzP0s/template-onsite-meeting-planning) +- Create a budget and check the contract for allowed amount. Then get approval from management if out-of-pocket budget is required +
[TEMPLATE: Onsite Travel Estimates](https://docs.google.com/spreadsheets/d/1dMNIFuhIeDMtqyp5oYpsLrXO9CVRZ-5ooPoR54doW7U/edit?usp=drive_web&ouid=103893616702532363241) +- Create invites on the project calendar for the onsite meetings and included participants +- Research hotels and coordinate booking details with our lead accountant +- Remind CivicActions participants to coordinate flights with our lead accountant +- Research meal options and coordinate with our lead accountant on food orders, delivery, and reservations +- [TEMPLATE: Discovery](https://trello.com/b/TtMYHp1i/template-discovery) includes a backlog of potential onsite discovery activities and may be useful if your onsite meetings are discovery-related diff --git a/practice-areas/project-management/pm-training.md b/practice-areas/project-management/pm-training.md index c3fed1cb04..7b1c083740 100644 --- a/practice-areas/project-management/pm-training.md +++ b/practice-areas/project-management/pm-training.md @@ -8,35 +8,35 @@ Review [The Project Manager Role](README.md) for an overview of PM responsibilit ## New PM Instructions -- New PMs should shadow other PMs calls, meetings, scrums, retrospectives, sprint demos, kick-offs, etc. -- New PMs to know how to react if someone calls on them unexpectedly, and how to quickly move along the meeting and get it back on track. The new PM should have a quick checkin like _"No project checkin. Here observing. Balance 8. I'll pass to Steve"_ -- New PM can practice taking meeting notes so they can compare their own notes from a meeting to the notes the PM actually shares with the team & client. New PMs can also take notes while current PM is still running meetings. +- New PMs should shadow other PMs calls, meetings, scrums, retrospectives, sprint demos, kick-offs, etc. +- New PMs to know how to react if someone calls on them unexpectedly, and how to quickly move along the meeting and get it back on track. The new PM should have a quick checkin like _"No project checkin. Here observing. Balance 8. I'll pass to Steve"_ +- New PM can practice taking meeting notes so they can compare their own notes from a meeting to the notes the PM actually shares with the team & client. New PMs can also take notes while current PM is still running meetings. ## Current PM Instructions -- All current PMs to look at their schedules and send invites to new PMs -- Current PMs to explain expectations of new PM roles on shadowing calls -- Current PMs to explain to team the role of the new PM on the calls (generally just observing and shouldn't be called upon unless they are actually part of that project) -- Current PMs to supply note templates should they exist (_ie scrum note template_) +- All current PMs to look at their schedules and send invites to new PMs +- Current PMs to explain expectations of new PM roles on shadowing calls +- Current PMs to explain to team the role of the new PM on the calls (generally just observing and shouldn't be called upon unless they are actually part of that project) +- Current PMs to supply note templates should they exist (_ie scrum note template_) ## Shadowing Calls -- PMs to shadow other PMs calls, meetings, scrums, retrospectives, sprint demos, kick-offs, etc. -- All current PMs to look at their schedules and send invites to new PMs -- Current PMs to explain expectations of new PM roles on shadowing calls -- Current PMs to explain to team the role of the new PM on the calls (generally just observing and shouldn't be called upon unless they are actually part of that project) -- New PMs to know how to react if someone calls on them unexpectedly, and how to quickly move along the meeting and get it back on track. The new PM should have a quick checkin like _"No project checkin. Here observing. Balance 8. I'll pass to Steve"_ -- Current PMs to supply note templates should they exist (_ie scrum note template_) -- New PM can practice taking meeting notes so they can compare their own notes from a meeting to the notes the PM actually shares with the team & client. +- PMs to shadow other PMs calls, meetings, scrums, retrospectives, sprint demos, kick-offs, etc. +- All current PMs to look at their schedules and send invites to new PMs +- Current PMs to explain expectations of new PM roles on shadowing calls +- Current PMs to explain to team the role of the new PM on the calls (generally just observing and shouldn't be called upon unless they are actually part of that project) +- New PMs to know how to react if someone calls on them unexpectedly, and how to quickly move along the meeting and get it back on track. The new PM should have a quick checkin like _"No project checkin. Here observing. Balance 8. I'll pass to Steve"_ +- Current PMs to supply note templates should they exist (_ie scrum note template_) +- New PM can practice taking meeting notes so they can compare their own notes from a meeting to the notes the PM actually shares with the team & client. ## Logging Internal Meetings ### Common Internal Meetings -- All Humans Call (AHC) -- Weekly Agile PM Meeting -- Pod Calls -- Check-ins with team members on performance & balance, etc. +- All Humans Call (AHC) +- Weekly Agile PM Meeting +- Pod Calls +- Check-ins with team members on performance & balance, etc. ## People Planning @@ -46,24 +46,24 @@ For a team member whose time is split between projects, Unanet helps plan how mu ## Scheduling Meetings -- The PM is generally the person to schedule all scrum ceremonies, client meetings, process meetings, and general team meetings. The team is also always welcomed to schedule one-off meetings for the internal team if they desire. -- Avoid scheduling meetings with blank descriptions in Google Calendar. Fill in a description/purpose for the meeting, link relevant documents, indicate the desired outcome, include an agenda, list discussion points, etc. -- Make a relevant and detailed meeting title. Make it descriptive and concise. -- Only require the necessary people, make other invitees optional. -- Check the FIND TIME function in Google Calendar to make sure you're not double-booking someone - it is crucial that you look at other people's calendars. +- The PM is generally the person to schedule all scrum ceremonies, client meetings, process meetings, and general team meetings. The team is also always welcomed to schedule one-off meetings for the internal team if they desire. +- Avoid scheduling meetings with blank descriptions in Google Calendar. Fill in a description/purpose for the meeting, link relevant documents, indicate the desired outcome, include an agenda, list discussion points, etc. +- Make a relevant and detailed meeting title. Make it descriptive and concise. +- Only require the necessary people, make other invitees optional. +- Check the FIND TIME function in Google Calendar to make sure you're not double-booking someone - it is crucial that you look at other people's calendars. ![Screenshot of "Find a time" tab when creating a google calendar event](../../assets/images/CivicActions_Calendar_FindTime.png "Finding Available Meeting Time") ## Timeboxing -- Consider turning on your clock's seconds so you can keep close eye on your timeboxes - You'll know if you have one minute or 5 seconds left. It helps! -- A role of the PM/ScrumMaster is to keep track of timeboxes by keeping communication on topic and moving efficiently. -- At the start of a meeting, announce the timebox for a meeting (any besides the 15 scrum) so the Scrum team knows how much meeting time to expect -- Divvy time up if you have multiple presenters and let each person know how much time they each have. -- Let folks know as a meeting progresses where timeboxes stand -- Thank people for their time commitments on longer meetings -- Have a timer handy - either an app or a physical one on your desk -- Acknowledge when the timebox has expired and make sure folks can stay longer if needed. +- Consider turning on your clock's seconds so you can keep close eye on your timeboxes - You'll know if you have one minute or 5 seconds left. It helps! +- A role of the PM/ScrumMaster is to keep track of timeboxes by keeping communication on topic and moving efficiently. +- At the start of a meeting, announce the timebox for a meeting (any besides the 15 scrum) so the Scrum team knows how much meeting time to expect +- Divvy time up if you have multiple presenters and let each person know how much time they each have. +- Let folks know as a meeting progresses where timeboxes stand +- Thank people for their time commitments on longer meetings +- Have a timer handy - either an app or a physical one on your desk +- Acknowledge when the timebox has expired and make sure folks can stay longer if needed. ![Screenshot of the clock on a Mac computer](../../assets/images/show-seconds.png "Showing seconds") @@ -73,31 +73,31 @@ Accurately estimating is one of the most difficult things to do. Developers shou ### Additional Resources -- -- +- +- ## Project Documentation -- Read ALL project documentation supplied by client -- Comprehend & ask questions about SoW & Contract -- Know what deliverables the project requires +- Read ALL project documentation supplied by client +- Comprehend & ask questions about SoW & Contract +- Know what deliverables the project requires ## Potential PM Project Deliverables -- Burn down and/or burn up reports -- Hours reports -- Monthly status -- Sprint plans -- Monthly deliverables -- Quarterly deliverables -- Integrated project plan (IPP) -- Release notes +- Burn down and/or burn up reports +- Hours reports +- Monthly status +- Sprint plans +- Monthly deliverables +- Quarterly deliverables +- Integrated project plan (IPP) +- Release notes ## PM Tools -- [Unanet](https://civicactions.unanet.biz) -- [Jira](../../common-practices-tools/software-and-support/jira.md) -- [GitHub](../../common-practices-tools/software-and-support/github.md) -- Burndown charts -- [Google Docs/Folders](../../common-practices-tools/software-and-support/google-docs.md) -- [Slack](../../common-practices-tools/software-and-support/slack.md) (client-facing and internal channels) +- [Unanet](https://civicactions.unanet.biz) +- [Jira](../../common-practices-tools/software-and-support/jira.md) +- [GitHub](../../common-practices-tools/software-and-support/github.md) +- Burndown charts +- [Google Docs/Folders](../../common-practices-tools/software-and-support/google-docs.md) +- [Slack](../../common-practices-tools/software-and-support/slack.md) (client-facing and internal channels) diff --git a/practice-areas/project-management/pm-unanet-tasks.md b/practice-areas/project-management/pm-unanet-tasks.md index 7a953cb2d6..aeb9a080d2 100644 --- a/practice-areas/project-management/pm-unanet-tasks.md +++ b/practice-areas/project-management/pm-unanet-tasks.md @@ -16,12 +16,12 @@ Unanet is an enterprise resource planning (ERP) system that CivicActions leverag ## Key Unanet tasks for a project lead -- [People planning and assignments (aka Plan with Grid)](https://docs.google.com/document/d/1716yCGd4K6zEtS1MN4Nsxk4MqwFKDcddc6F77UXgY3M/edit) -- [People planning and assignments by Day (aka Plan with Grid by Day)](https://docs.google.com/document/d/1KqkkKJSOQk_g1a0UA5n3bLAm4yMvoOgkRsPgKVtD-5g/edit) -- [Reviewing and approving timesheets](https://docs.google.com/presentation/d/1sOcMvmC_VFuY_DJhzFDMFcFvbV6y14JcBwTeOimiWjc/edit#slide=id.gca7c90bf59_0_66) -- [Reviewing and approving expenses](https://docs.google.com/document/d/1fTwAs9OPKvqHwaH6bABaQUnvDpnULXpHX4HcgE3v0Tc/edit) -- [Running reports: Plans vs Actuals](https://docs.google.com/document/d/1yIcQsi_vCIiK1iqd3r-UBiqmv5s5XDnIhjJqw6MA8xo/edit) -- [Running reports: Planned Utilization](https://docs.google.com/document/d/1RGX5hP_nFFi9gEdUnWKqvyBMmKaRsjF251Esn3CuHgU/edit) +- [People planning and assignments (aka Plan with Grid)](https://docs.google.com/document/d/1716yCGd4K6zEtS1MN4Nsxk4MqwFKDcddc6F77UXgY3M/edit) +- [People planning and assignments by Day (aka Plan with Grid by Day)](https://docs.google.com/document/d/1KqkkKJSOQk_g1a0UA5n3bLAm4yMvoOgkRsPgKVtD-5g/edit) +- [Reviewing and approving timesheets](https://docs.google.com/presentation/d/1sOcMvmC_VFuY_DJhzFDMFcFvbV6y14JcBwTeOimiWjc/edit#slide=id.gca7c90bf59_0_66) +- [Reviewing and approving expenses](https://docs.google.com/document/d/1fTwAs9OPKvqHwaH6bABaQUnvDpnULXpHX4HcgE3v0Tc/edit) +- [Running reports: Plans vs Actuals](https://docs.google.com/document/d/1yIcQsi_vCIiK1iqd3r-UBiqmv5s5XDnIhjJqw6MA8xo/edit) +- [Running reports: Planned Utilization](https://docs.google.com/document/d/1RGX5hP_nFFi9gEdUnWKqvyBMmKaRsjF251Esn3CuHgU/edit) ## Adjust projections for holidays or other OOO diff --git a/practice-areas/project-management/project-calendar.md b/practice-areas/project-management/project-calendar.md index fa4c09982c..db1daa655c 100644 --- a/practice-areas/project-management/project-calendar.md +++ b/practice-areas/project-management/project-calendar.md @@ -10,15 +10,15 @@ Most larger projects have their own Google Calendar, which is often created by t ## Calendar creation tips -- Upon calendar creation, name the calendar to align with the client, unless there are concurrent projects for the client -- Edit all events on the project calendar instead of personal calendars -- Settings: Auto-accept invitations > Automatically add all invitations to this calendar -- Settings: Access permissions > Make available for CivicActions > See all event details -- Settings: Share with specific people > Invite all CivicActions project team members to the calendar -- Direct team member should be able to > Make changes to events -- Settings: Share with specific people > Invite delivery and Ops team members as appropriate to the calendar -- Indirect team members should be able to > See all event details -- It is typical that clients are invited to events on a project calendar +- Upon calendar creation, name the calendar to align with the client, unless there are concurrent projects for the client +- Edit all events on the project calendar instead of personal calendars +- Settings: Auto-accept invitations > Automatically add all invitations to this calendar +- Settings: Access permissions > Make available for CivicActions > See all event details +- Settings: Share with specific people > Invite all CivicActions project team members to the calendar +- Direct team member should be able to > Make changes to events +- Settings: Share with specific people > Invite delivery and Ops team members as appropriate to the calendar +- Indirect team members should be able to > See all event details +- It is typical that clients are invited to events on a project calendar ## Contractual Calendar diff --git a/practice-areas/project-management/project-folder.md b/practice-areas/project-management/project-folder.md index b7140a7d5f..4f35c29373 100644 --- a/practice-areas/project-management/project-folder.md +++ b/practice-areas/project-management/project-folder.md @@ -8,8 +8,8 @@ Project Folders are integral to our transparency tenet at CivicActions. They als We aim for consistency across projects as follows: -- The project folder names are similar to Unanet and all other references to the project (e.g., Wrappers, Onboarding deck, etc.) -- There are two project folders: (project name) Internal; (project name) External +- The project folder names are similar to Unanet and all other references to the project (e.g., Wrappers, Onboarding deck, etc.) +- There are two project folders: (project name) Internal; (project name) External The structure inside the External or Internal folders are determined by the team. Having obvious separation between sub-teams or focus areas is highly encouraged. If approroached from the aspect of permissions, this task becomes more clear. @@ -17,24 +17,24 @@ Clients are allowed permissions for sub-folders within External. It is recommend ## Structure Highlights -- The External folder includes the whole project team and the major client stakeholders -- The Internal folder will include only the CivicActions project team -- The majority of the documents, materials, etc., will land within the External folder (we rely on being transparent with out project documents to provide the whole team with the access they need) -- The Internal folder typically includes internal documents related to budget planning, invoicing, proposal documents, etc. -- There are situations that merit a third folder for scenarios like third-party stakeholders who need a different level of access to documents (often paired down content) +- The External folder includes the whole project team and the major client stakeholders +- The Internal folder will include only the CivicActions project team +- The majority of the documents, materials, etc., will land within the External folder (we rely on being transparent with out project documents to provide the whole team with the access they need) +- The Internal folder typically includes internal documents related to budget planning, invoicing, proposal documents, etc. +- There are situations that merit a third folder for scenarios like third-party stakeholders who need a different level of access to documents (often paired down content) ## Example Folder Structures -- [External Folder Structure](https://drive.google.com/drive/folders/12A_IvfJItWrCLoGFR0PPcS1zQNzedS2u) -- [Internal Folder Structure](https://drive.google.com/drive/folders/1sDEFlOEJz8dpJpA3B_UqhJflXrs6L6hj) +- [External Folder Structure](https://drive.google.com/drive/folders/12A_IvfJItWrCLoGFR0PPcS1zQNzedS2u) +- [Internal Folder Structure](https://drive.google.com/drive/folders/1sDEFlOEJz8dpJpA3B_UqhJflXrs6L6hj) ## Ongoing Maintenance from the Project Manager Common challenges with project folders include the following: -- The folders can become unruly -- Not all project documents are saved in the folders -- Resourcing changes require permission adjustments +- The folders can become unruly +- Not all project documents are saved in the folders +- Resourcing changes require permission adjustments The Project Manager [checklist](project-management-checklists.md) includes folder maintenance. Project Managers are encouraged, at least once per month, to review all project folders to complete the following: -Shifting unused or unnecessary documents to an Archive folder diff --git a/practice-areas/project-management/project-offboarding.md b/practice-areas/project-management/project-offboarding.md index 1f0a0abbcb..599129629f 100644 --- a/practice-areas/project-management/project-offboarding.md +++ b/practice-areas/project-management/project-offboarding.md @@ -4,90 +4,90 @@ title: Offboarding # Offboarding A Team Member from a Project -- The project team is responsible for doing project specific offboarding. However, there is a company offboarding process where non-project specific offboarding is already tracked. -- The Project Manager should use a Trello card or Jira ticket (depending on the tool the project uses) to track offboarding tasks after the contractor's work is completed to ensure the contractor is properly removed from CivicActions tools, files, and the project. Consider preparing this ticket at the time of contractor onboarding so you have a place you can track all tools to which they are added over time. -- The Project Manager should also coordinate offboarding tasks with appropriate team members (UX, TL, etc) to ensure that the remainder of the tasks are completed. +- The project team is responsible for doing project specific offboarding. However, there is a company offboarding process where non-project specific offboarding is already tracked. +- The Project Manager should use a Trello card or Jira ticket (depending on the tool the project uses) to track offboarding tasks after the contractor's work is completed to ensure the contractor is properly removed from CivicActions tools, files, and the project. Consider preparing this ticket at the time of contractor onboarding so you have a place you can track all tools to which they are added over time. +- The Project Manager should also coordinate offboarding tasks with appropriate team members (UX, TL, etc) to ensure that the remainder of the tasks are completed. ## Offboarding team members with legacy information who may return to consult SCENARIO: Team member is leaving a project but will be retained as a "legacy consultant" for the active project team. (Assuming project does not require clearance and doesn't handle sensitive data). -- Project Jira access - block if user limit is reached -- Git - no change -- Server - no change -- Site user accounts (Drupal, etc) - no change -- SSH login - no change -- Project Slack channels - no change -- Project email lists - no change -- Google Shared folders - no change -- LastPass shares - no change -- Project Trello boards - no change -- UX tools - no change -- Calendar invites - remove or ask if they want to stay on any -- Audit accounts spreadsheet - update +- Project Jira access - block if user limit is reached +- Git - no change +- Server - no change +- Site user accounts (Drupal, etc) - no change +- SSH login - no change +- Project Slack channels - no change +- Project email lists - no change +- Google Shared folders - no change +- LastPass shares - no change +- Project Trello boards - no change +- UX tools - no change +- Calendar invites - remove or ask if they want to stay on any +- Audit accounts spreadsheet - update ## Offboarding team members who will not return to the project SCENARIO: Team member finishes project work and probably won't come back to project. SCENARIO: Project requires security clearance and/or handles sensitive data and team member is "off" project -- Project Jira access - block -- Git - block -- Server - remove -- Site user accounts(Drupal, etc) - block -- SSH login - remove -- Project Slack channels - remove from client channels & ask if they want to leave internal -- Project email lists - remove -- Google Shared folders - remove -- LastPass shares - remove -- Project Trello boards- remove -- UX tools - no change or block project -- Calendar invites - remove -- Directnic access - remove -- Audit accounts spreadsheet - update +- Project Jira access - block +- Git - block +- Server - remove +- Site user accounts(Drupal, etc) - block +- SSH login - remove +- Project Slack channels - remove from client channels & ask if they want to leave internal +- Project email lists - remove +- Google Shared folders - remove +- LastPass shares - remove +- Project Trello boards- remove +- UX tools - no change or block project +- Calendar invites - remove +- Directnic access - remove +- Audit accounts spreadsheet - update ## Offboarding a team member who leaves the company SCENARIO: When this team member leaves the company they should be fully offboarded. -- Project Jira access - block -- Git - remove -- Server - remove -- Site user accounts(Drupal, etc) - block -- SSH login - remove -- Project Slack channels - remove -- Project email lists - remove -- Google Shared folders - remove -- LastPass shares - remove -- Project Trello boards - remove -- UX tools - remove -- Calendar invites - remove -- Directnic access - remove -- Audit accounts spreadsheet - update -- Project specific GSuite access - remove -- Project specific CPM access - remove -- Basic Auth login - change -- Request all project data be remove from personal computer +- Project Jira access - block +- Git - remove +- Server - remove +- Site user accounts(Drupal, etc) - block +- SSH login - remove +- Project Slack channels - remove +- Project email lists - remove +- Google Shared folders - remove +- LastPass shares - remove +- Project Trello boards - remove +- UX tools - remove +- Calendar invites - remove +- Directnic access - remove +- Audit accounts spreadsheet - update +- Project specific GSuite access - remove +- Project specific CPM access - remove +- Basic Auth login - change +- Request all project data be remove from personal computer ## Offboarding a contractor from a project SCENARIO: The contractor completes all project work/project ends they should be fully offboarded. -- Project Jira access - block -- Git - remove -- Server - remove -- Site user accounts (Drupal, etc) - block -- SSH login - remove -- Project Slack channels - remove -- Project email lists - remove -- Google Shared folders - remove -- LastPass shares - remove -- Project Trello boards - remove -- UX tools - remove -- Calendar invites - remove -- Audit accounts spreadsheet - update -- Project specific GSuite access - remove -- Project specific CPM access - remove -- Basic Auth login - change -- Request all project data be remove from personal computer -- PM or TL to conduct exit interview and capture notes +- Project Jira access - block +- Git - remove +- Server - remove +- Site user accounts (Drupal, etc) - block +- SSH login - remove +- Project Slack channels - remove +- Project email lists - remove +- Google Shared folders - remove +- LastPass shares - remove +- Project Trello boards - remove +- UX tools - remove +- Calendar invites - remove +- Audit accounts spreadsheet - update +- Project specific GSuite access - remove +- Project specific CPM access - remove +- Basic Auth login - change +- Request all project data be remove from personal computer +- PM or TL to conduct exit interview and capture notes diff --git a/practice-areas/project-management/starting-new-project.md b/practice-areas/project-management/starting-new-project.md index fdf08fb1a0..21a66d57d9 100644 --- a/practice-areas/project-management/starting-new-project.md +++ b/practice-areas/project-management/starting-new-project.md @@ -10,49 +10,49 @@ It may be helpful to copy these lists into a card/checklist on your project Trel ### Prep Work -- Hand-off call with Sales team -- Validate that SOW has been signed and review prior SOWs if relevant -- Review contract and proposal -- Review staffing and staffing gaps -- Fill out [New Client/Project Startup form](https://docs.google.com/a/civicactions.com/forms/d/1UoLOeP0NgsNNDHfRbo50zE2onRuWQ4K-hHB2Q-RFcF8/viewform) (this goes to the Office Manager) -- Work with Admin to organize background checks or drug tests if needed -- Determine if there are any specific time reporting or invoicing needs for client -- Hand-off call with Admin regarding contract/compliance/invoicing details -- Work with the Delivery Manager (DM) to assign project team -- Share SOWs and NDAs, as necessary, with ca-admingroup -- Set up tracking for [contractual requirements](contractual-requirements.md) -- Set up tracking for [contract expiration/renewal](contract-expiration-tracking.md) -- Review project hours thus far: determine if billable to client, or accountable to Sales (ask DM if you are not sure) -- Request copy of client travel policy if not included in contract or SOW +- Hand-off call with Sales team +- Validate that SOW has been signed and review prior SOWs if relevant +- Review contract and proposal +- Review staffing and staffing gaps +- Fill out [New Client/Project Startup form](https://docs.google.com/a/civicactions.com/forms/d/1UoLOeP0NgsNNDHfRbo50zE2onRuWQ4K-hHB2Q-RFcF8/viewform) (this goes to the Office Manager) +- Work with Admin to organize background checks or drug tests if needed +- Determine if there are any specific time reporting or invoicing needs for client +- Hand-off call with Admin regarding contract/compliance/invoicing details +- Work with the Delivery Manager (DM) to assign project team +- Share SOWs and NDAs, as necessary, with ca-admingroup +- Set up tracking for [contractual requirements](contractual-requirements.md) +- Set up tracking for [contract expiration/renewal](contract-expiration-tracking.md) +- Review project hours thus far: determine if billable to client, or accountable to Sales (ask DM if you are not sure) +- Request copy of client travel policy if not included in contract or SOW ### Project Setup -- Ensure project is set up in Unanet -- Update People Assignments and Plans -- Set up Shared Google Drive folders for projects using the consistent [project folder structure](project-folder.md) -- Set up [project email lists](listserv-setup.md) (decide if you need both internal and client facing) -- Set up project Slack channels (internal and client facing) -- With Tech Lead (TL), set up any/all Trello boards or JIRA instances -- Send orientation / welcome email (Slack, team intros, email intro, call schedules and project schedule) to project email list(s) -- Confirm any deviation from standard green-lighting (contract signed, etc.) with DM and CEO -- Set up hosting (if needed) -- Determine infrastructure needs for client (VPN access, demo system access, source code access, etc.) -- Schedule internal kickoff and client kickoff -- Review invoicing in contract and prepare [invoicing documentation](invoicing.md) +- Ensure project is set up in Unanet +- Update People Assignments and Plans +- Set up Shared Google Drive folders for projects using the consistent [project folder structure](project-folder.md) +- Set up [project email lists](listserv-setup.md) (decide if you need both internal and client facing) +- Set up project Slack channels (internal and client facing) +- With Tech Lead (TL), set up any/all Trello boards or JIRA instances +- Send orientation / welcome email (Slack, team intros, email intro, call schedules and project schedule) to project email list(s) +- Confirm any deviation from standard green-lighting (contract signed, etc.) with DM and CEO +- Set up hosting (if needed) +- Determine infrastructure needs for client (VPN access, demo system access, source code access, etc.) +- Schedule internal kickoff and client kickoff +- Review invoicing in contract and prepare [invoicing documentation](invoicing.md) ## Client Kickoff Meeting -- See [Kickoff Meeting Agenda template](https://docs.google.com/document/d/1pmOruj_1PeSfmJtxzvjDy7KxTTJi0VS8D62WUrWjeSM/edit). +- See [Kickoff Meeting Agenda template](https://docs.google.com/document/d/1pmOruj_1PeSfmJtxzvjDy7KxTTJi0VS8D62WUrWjeSM/edit). ## Early Project Activities -- [Onboard team members](onboarding-new-project-team-member.md) -- Schedule first week activities with client (if needed) -- Overall Project plan -- Communication / Escalation plan - internal and external facing -- Schedule Status Meetings with client -- Schedule [scrum calls](../../common-practices-tools/agile/daily-scrum-calls.md) -- Risk tracking / mitigation plan -- Identify key stakeholders -- Set up first Status Report -- Set up Contact List +- [Onboard team members](onboarding-new-project-team-member.md) +- Schedule first week activities with client (if needed) +- Overall Project plan +- Communication / Escalation plan - internal and external facing +- Schedule Status Meetings with client +- Schedule [scrum calls](../../common-practices-tools/agile/daily-scrum-calls.md) +- Risk tracking / mitigation plan +- Identify key stakeholders +- Set up first Status Report +- Set up Contact List diff --git a/practice-areas/project-management/team-working-agreements-instructions.md b/practice-areas/project-management/team-working-agreements-instructions.md index d88751e87f..9b977277ff 100644 --- a/practice-areas/project-management/team-working-agreements-instructions.md +++ b/practice-areas/project-management/team-working-agreements-instructions.md @@ -30,9 +30,9 @@ The Project Management Practice Area will prepare the Team Working Agreement (TW Using the [survey template](https://docs.google.com/forms/d/1f1hnFe-ZvjEU-MXOSJAB3UyOuedwMp_ZsRjpKRIUrxA/edit), conduct a devoted call with the team every quarter to review priority elections. Remind the team about participation in at least the following instances: -- Prior to sending the survey and including the submission deadline -- During the survey period -- Prior to closing the survey period +- Prior to sending the survey and including the submission deadline +- During the survey period +- Prior to closing the survey period Following the survey, all results are tallied and inserted into this document, including a link to the survey with full transparency on the values entered. @@ -52,10 +52,10 @@ This section is started by the Technical Lead(s) with the objective of creating This section is started by the Project Manager, perhaps noting two things: -- How the team recognizes good work presently -- Suggestions for other recognition methods - During TWA discussions, the team is able to adjust details as desired, including around iterative discussion mediums and timelines. - NOTE: One great function the TWA can play is to become a best practices repository for the team. If, for an example, a good suggestion surfaces in a Retro, the team can ask, "Should this be in our TWA?" +- How the team recognizes good work presently +- Suggestions for other recognition methods + During TWA discussions, the team is able to adjust details as desired, including around iterative discussion mediums and timelines. + NOTE: One great function the TWA can play is to become a best practices repository for the team. If, for an example, a good suggestion surfaces in a Retro, the team can ask, "Should this be in our TWA?" ## Billable Targets @@ -71,11 +71,11 @@ The TWA requires quarterly review. The team can decide if there is a committee o The key sections to review are those marked with an asterisk. The ongoing objectives are as follows: -- To confirm all team members are included -- To verify that team members are accurate -- To reflect any logistical changes -- To represent the agreement of the team -- To keep abreast on team recognition -- To keep innovation in front of the team +- To confirm all team members are included +- To verify that team members are accurate +- To reflect any logistical changes +- To represent the agreement of the team +- To keep abreast on team recognition +- To keep innovation in front of the team The Project Manager is responsible to guide the document review dates, yet any team member is welcome to own the TWA. diff --git a/practice-areas/project-management/templates.md b/practice-areas/project-management/templates.md index 1e5a3316ce..e4fe2356e2 100644 --- a/practice-areas/project-management/templates.md +++ b/practice-areas/project-management/templates.md @@ -14,10 +14,10 @@ If a project requires additional resourcing, i.e., for a work surge or else to s How? Use Slack, the project Core channel, and this framework, requesting alignment and opening it for questions: -- Rationale for adding/increasing resourcing -- Impact to financial health (i.e., the effective rate is predicted to be $X for Y months) -- Expected duration -- Please CC Alaine, Elizabeth and Bill +- Rationale for adding/increasing resourcing +- Impact to financial health (i.e., the effective rate is predicted to be $X for Y months) +- Expected duration +- Please CC Alaine, Elizabeth and Bill ## Budget tracking