Create a developer handbook that this initiative is following

[MariusStorhaug]

Developer handbook

What are our:

• Practices
• Methodologies
• Tools

Way of working

Continiuous Planning

• Clearly define a vision statement. 3 levels of 3 horizons (Strategic, Initiatives, Delivery | Now, Next, Later)

• OKRs

• Clearly understand what a successful release (small batch iteration) contains.

• Figure out the details of how to get there only when you need to do so.

• Create a detailed plan only for parts that are 100% clear at the last responsible moment:

  • Just in time (when you are about to implement in the upcoming 1-3 sprints)
  • When you have enough information to get started (just enough clarity is good enough)

• Conduct hypothesis-based development on that detailed plan to build and learn.

• Use the validated learning from the aforementioned hypothesis to create additional clarity in the high-level plan.

• Prioritization

  • MOSCOW
    • Must have
    • Should have
    • Could have
    • Would/won’t have

• Backlog is stack ranked, or ordered. It specifically calls out in which order backlog items should be implemented. Ranking items in the order they should be executed facilitates better trade-off conversations and eliminates confusion over what is most important.
  Backlog items are prioritized by value, be it ROI or cost-of-delay.

User story definition

• Definition of done
  • A list of criteria agreed upon by the team and understood by everyone that must be met before any product increment is considered “done” and includes any system-level non-functional attributes (aka NFRs).
    • This is not customer approval.
    • Failure to meet these criteria at the end of a sprint implies that the work is not counted toward the sprint’s output.
• Acceptance criteria
  • The universal understanding about whether the feature, user story, or work is “done” and includes description of the non-functional attributes (aka NFRs) of the work unit.
    • Usually a description of what can be tested to validate “done.”
    • The basis for all audits and approvals of quality.

Practices

• Product and outcome centric mindset
  • Outside-in
  • Output-focussed
• Start fast, deploy for use and iterate quickly
• Cross-functional teams
• Seek data-driven continuous improvement
• Security and quality by design
• Automate everything
• 4eyes

Being product-centric

• Rythm and cadence
  • Align rythm
  • Think n-2 (2 sprints ahead)
    • Now, Next, Later
    • Now are small and specific, (easy to estimate)
    • Later are big and fluffy (hard to estimate)
• Team structure
  • Priorities on local level
  • Auton
• Agile practices and execution
• Product planning rythm
• Product discovery

List of some things:

• PowerShell Practices and Style
• PowerShell Best Practices and Style Guide
• Code With Engineering Playbook
  • Docs
  • GitHub repo
• Microsoft Writing Style Guide

Principals and processes to follow:

• Lean software development
• SOLID
• DRY
• DAMP/Clean code/Nevernester
• "Start with why"
• Value proposition
  • For $Customer who $Qualifier, $Product $ValueStatement. Unlike $Alternative, $Product $Differentiator) - Monad Manifesto

Process

1. Question all requirements. Make sure the requirements are valid and necessary.
2. Remove things that should not be there. Delete the part or process, if things are not added back in, you are not deleting enough.
3. Simplify or optimize, most common error is to optimize something that should not exist.
4. Streamline and improve the cycle time.
5. Automate.

On user stories

Well-written user stories use the INVEST model, which identifies six important properties:

• Independent
  • Eliminate or simplify dependencies between stories
  • Product owner and team work together
  • Achieved through proper decomposition
• Negotiable
  • Team and product owner work together
  • Discuss feasibility
  • Renegotiate to decompose stories
  • Splitting stories across sprints is acceptable
  • Product owner is always responsible for prioritization
• Valuable
  • Stories must have a demonstrable increase in value
  • Partial value is acceptable
  • Avoid unusable components
  • Avoid technical terms
• Estimable
  • Avoid open-ended stories - general quality checks are for the definition of done
  • Be specific - the team cannot estimate vague requests
  • If we cannot estimate it, we don’t understand it! Consider decomposing for research and implement in a follow up sprint.
• Small
  • Must be done in a sprint!
  • Rule of thumb examples: No more than half a sprint; between 1/3 and 1/5 of the team’s velocity; and takes up to 5 days to complete
  • Can be created as an epic and decomposed later - decompose stories during backlog refinement, in time for the sprint
• Testable
  • A PBI is done only if completed successfully
  • Requires sufficient information
• Specific
  • Unambiguous - the product owner is the final arbiter

Early adopters (enterprises with low agile maturity) should apply agile offerings to a small project and use on-site supplier developers.

• They will need more hand-holding with help from agile coaches to transition to a new agile way of working.
• Teams that blend customer and supplier personnel are most appropriate in this phase.
• The biggest challenge is to identity the right pilot project to get started. Enterprises should shortlist projects that will cause little disruption to business operations.

Growing adopters (enterprises with medium agile maturity) have some experience in applying agile with limited outcomes.

• They can improve further by assessing team structure, stakeholder contributions, process, and technology adoption.
• To encourage vendor accountability, everyone within a team except the product owner should come from the same supplier.
• At this level of maturity, consider a managed-capacity contracting model where the vendor teams are assigned specific tasks and evaluated on story points.

Confident and mature adopters (enterprises with significant agile maturity) should continue to experiment with new models and use effective metrics.

• The focus should be to estimate business value and tie increased business value to features.
• They can use distributed agile teams and make use of both nearshore and onshore developers to derive more business value.

Backlog refinement
What it is
Backlog refinement is an exercise in which the product owner and some (or all) of the team review backlog items to help ensure priority and fidelity.

How to conduct a backlog refinement exercise
Remove user stories that no longer appear relevant.
Create new user stories in response to newly discovered needs.
Assess relative priority of stories.
Assign estimates to stories that have yet to receive one.
Correct estimates in light of newly discovered information.
Split user stories that are high priority but too coarse-grained to fit in an upcoming iteration.
Ensure user stories have information to be estimable for sprint planning.
The value of this exercise lies in the principles it’s based on, such as design thinking, simplicity, and Lean management, and not the components of the exercise.

Sprint planning
Sprint planning is the kickoff to every sprint

Objective: team commitment to user stories/scope to be committed for the next sprint.

Sprint planning consists of four primary activities:

Confirm dates for sprint review and customer demonstrations
Product owner communicates the sprint goal and/or customer demonstration use cases
At the end of every sprint, show off what’s been pushed to a production-like environment.
Review proposed user stories
Assuming backlog refinement is happening regularly and effectively to prioritize and estimate all user stories in the upcoming sprint, this should be straightforward and a simple exercise in commitment agreement.
Set team capacity
Be realistic and honest about you and your development team’s time and account for vacations and other sprint ceremonies.
Commitment
Output of this meeting should be team agreement on user stories to take into the sprint based on user story sizing and team capacity.

Daily scrum
Daily scrum participants should answer three basic questions:

What did I do yesterday to help the team achieve the sprint’s goal?
What do I plan to do today to help achieve the sprint’s goal?
Do I see any impediments that may jeopardize the sprint’s goal?
Daily scrums should

Focus on the team’s shared goal
Exhibit efficient communication
Spawn additional collaboration
Instantly remove impediments
Assume fast situational awareness for everyone
Be of less than 15 minutes’ duration
Reinforce the idea of scrum as a highly disciplined process
NOT be a status reporting exercise
It’s fine for daily scrums to spawn additional collaboration after the meeting. Not all team members need to be involved in everything, but it’s good for all team members to be aware of all efforts.

Daily scrums that take more than 15 minutes are an indicator of a lack of discipline (stick to the agenda) or a larger problem.

Actually standing up during the meeting is a generally accepted practice that helps keep it short but is not required – everyone should be able to participate in scrum.

Sprint reviews

Sprint review considerations:

Delivering an increment of working software at the end of every sprint is the most important commitment the team makes.
Long periods of time - for example, more than one sprint - without working software is an indicator of trouble.
It’s not OK for the team to say that certain sprints don’t result in working software.
Working software is a key driver of customer feedback.

Customer demonstrations achieve the following:

Enforce the commitment to developing working software.
Provide the customer with confidence about the team’s progress towards their desired outcome.
Lead to customer feedback, possibly resulting in backlog changes.
Prompt the customer to do user acceptance testing.
Help ensure that deployment is predictable.

Retrospectives
...

Continuous Integration

• Long development cycles

  • Non-compiling code.
  • At any point in time source code may not be functional.
  • Code freezes.

• High build failures/bug counts

  • Long living branches, causing multi-day merge efforts.
  • Code missing from source control.
  • Security flaws found late in development cycle.
  • Large amount of technical debt.
  • No/low code coverage numbers.
  • Overall reduced quality

• Limited communication and collaboration

  • Code not following coding standards.
  • No or few code reviews.
  • Testing done late in development cycle.
  • Testing in many cases manual if at all.

CI Goals:

• Harness collaboration
• Enable parallel development
• Minimize integration debt
• Act as a quality gate
• Automate everything

CI:

• Version Control System
• Branching strategy
• Automated build/test

Mono-repos and multi-repos
Feature branching
Trunk-based branching
Git pull requests
Branching policies
Automated builds

Functions for Continuous Integration include:

Behavior-driven development (BDD)
Test-driven development
Always run all “commit tests” locally before check-in
Wait for “commit tests” to pass before moving on
Don’t comment out failing tests
Don’t check in a broken build
Never go home on a broken build
Always be prepared to revert to the previous revision
Time-box fixing before reverting
Every check in is “production grade”
Take full responsibility for all breakages that result from your changes

Everything as code
All project elements should be subject to source control, including:

Application source code.
Database schema.
Seed or look-up data.
Test data.
Application configuration (Configuration as code).
Infrastructure configuration (Infrastructure as code).

Accelerate

Maturity model -> Capabilities model

It’s output / business goal oriented
Key capabilities
Product offerings

Mttr - mean time to recover
Lead time

Develop the what, and the how

Shorter = better feedback loops
Code committed -> it’s running in main

Batch sizes = easier to get to main
Deployment frequency is a proxy for lead time
Proves adoption of continuous integration on deployment

Culture shift by grassroots movement/change.
Implementing CI/CD will change culture

Automate everything vs ROI and criticality

How to prioritize what to automate first?
Everything as code introduces Version control
Shift left test and security

Githubflow vs Trunk based
TDD of platform, Pester and deploy a solution which should/should not feel.
Accelerators can be available as option.
Refrain from inducing naming conventions on teams. Let them define their own for their own services.

Allow teams to choose their own tools.

Suitability
Experimentation
Performance

Tools and architecture to provide wanted outcomes.
Platform configuration is system critical/sensitive info. Protect code from insight to need to know?

Rugged manifesto

WIP limits

External have negative impact on dev performance. No change management has positive impact?!!!
Lightweight change management - Avoid CABs as external teams having to approve changes. Only peer review or peer programming!

Triage changes - PIM
Bring back to code

Lean 8.1

MVP
Flow of work - visibility
Seek customer feedback
Authority to change specs on product internally in the team - no external approval

Team objective
Help to develop a team with world class Platform DevOps engineers.

Design decisions

PowerShell projects

Repository

• A repository manages ONE module.
• A repository has releases that are in line with the version of the published package.
• The version of a repository follows semver 2.0.0 based on the changes to the module, and not the framework or any other external factor from the module.

Repository structure

• The output folder = .\outputs on the root of the repo.
• The module that is build is stored under the output folder in a folder with the same name as the module.

The test and build process is based on the following repository structure. The PSModule framework is expecting the modules to follow this structure as some of the
paths and calculations are based on this structure. Not following this might result in the build process not working as expected.

.
├─ .github/
│  └- workflows/
│     └- Process-PSModule.yml              # The workflow file based on [Process-PSModule](https://github.com/PSModule/Process-PSModule) template.
├─ .vscode/                                # The settings for the Visual Studio Code aligned with the PSModule framework formatting and linting practices.
├─ icon/
|  └- <icon>.png                           # Icon file automatically used in the module manifest file if nothing else is specified.
├─ outputs/                                # The output folder created during build. This is a temporary folder that should not be committed to the repository.
|  ├─ docs/                                # The output folder for the documentation.
|  |  └─ ModuleName/                       # The output folder for the module.
|  └─ modules/                             # The output folder for the module.
|     └─ ModuleName/                       # The output folder for the module.
├─ src/                                    # The source code for the module.
│  ├─ ModuleName/                          # The source code folder for the module. Kept like this for ease of testing. This folder can be loaded as a module.
│  │  ├─ assembly/                         # All .dll files are collected to RequiredAssemblies
│  │  │  └─ <dlls>                         # loaded during import via RequiredAssemblies
│  │  ├─ classes/                          # All .ps1 files are collected to ScriptsToProcess and loaded to the caller session (parent of module session)
│  │  │  ├─ <ClassName>.ps1                # loaded during import via ScritsToProcess
│  │  │  ├─ <ClassName>.Format.ps1xml      # loaded during import via FormatsToProcess (collected based on *.Formats.ps1xml files in the root of the folder)
│  │  │  └─ <ClassName>.Types.ps1xml       # loaded during import via TypesToProcess (collected based on *.Types.ps1xml files in the root of the folder)
│  │  ├─ data/                             # Loads .psd1 files into the module session.
│  │  ├─ en/
│  │  |  ├─ en-US/                         # Search here first for OS = en-US, then parent, en. Get-Help and platyPS reads this.
│  │  │  └─ about_<ComponentName>.help.txt
│  │  ├─ init/                             # All .ps1 files are added to the root module and can contain scripts that run during import before functions are loaded.
│  │  ├─ modules/                          # All .dll, psm1 and ps1 files are collected to NestedModules and loaded to the module session.
│  │  ├─ private/                          # All .ps1 files are added to the root module, but not exported to the caller session.
│  │  ├─ public/                           # All .ps1 files are added to the root module, and exported to the caller session.
|  |  ├─ resources/                        # All .psm1 files are collected to DscResourcesToExport and loaded to the module session.
│  │  ├─ scripts/                          # All .ps1 files are collected to ScriptsToProcess and loaded to the caller session (parent of module session)
|  |  ├─ <ScriptName>.ps1                  # All *.ps1 files are added to the root module last and can contain scripts that run during import after functions are loaded.
|  |  ├─ header.ps1                        # Added to the root module first. Typically for Pester supressions and [CmdletBinding()].
│  │  ├─ ModuleName.psd1                   # The module manifest file, if not present, it is generated.
│  │  └- ModuleName.psm1                   # The root module file, if not present, it is generated from the source files.
├─ tests/
│  └- ModuleName/
│     └- ModuleName.Tests.ps1
├─ .gitattributes
├─ .gitignore
├─ LICENSE                                 -> The license file for the module. Used in the module manifest file.
└─ README.md

Modules

Principles for module design

• Plain function names regarding resources that is managed by a function
• Plain parameter names matching the typical names used by the API but "normalized" to human language + PowerShell common guidelines (i.e. casing)
• Pipelining and parallel processing by default
• Use modern authentication where available
• Built in support to be run locally as well as on a CI/CD runner
• Allow sessions to reuse existing auth (no reauth required)
• Telemetry built in (use a common library, powershell module)
• Logging built in (use a common library, powershell module)

To be filled later.

API specs to PowerShell

PowerShell verb	API Method	Description
Get	Get	Gets one or more of a given item
Update
Set	Mix	Declare the settings for the resource
Add	Put/Post	Create a new update
Remove	Delete	Remove the resource from existence

What-if for any state changing functions

All functions must support a what-if functionality that shows the change that is happening via Get, and mocking the new object + doing a comparison. The what-if object should be able to be retrieved by a the caller.

Functions

...

Documentation

• Documentation uses comment-based documentation, placed first in the function block.
• Documentations contains synopsis, description (not copy paste from synopsis), atleast one example.
  • If the function generates outputs, the output should be documented using the .OUTPUT <OutputType> doc tag.
  • If the function takes input by pipeline, the input should be documented using the .INPUT <InputType> doc tag.
• Parameter documentation that are not dynamic, exists inside the param() block, above the function.

Manifest

• The ModuleVersion is generated from the Publish-PSModule function, based on available version and lables on PRs, not from the module manifest.
• The basis of the module manifest comes from the source manifest file.
• Values that are not defined in the module manifest file are generated from reading the module files and github repository properties.
• If no RootModule is defined in the manifest file, a file with the name of the folder is searched for with a compatible file extension.
• A new module manifest file is created every time to get a new GUID, so that the specific version of the module can be imported.

GitHub Action and workflow projects

Actions and reusable workflows

• Use the composite action to load prerequisite modules. I.e., 'Utilities'.
• Run the main functionality from a main.ps1 file located in a scripts folder.
• The action inputs are written in PascalCase and uses the natural language name of the input.
• Use envvironment variables to pass data between the composite action and the main.ps1 file.
• Prefix the environment variable with GITHUB_ACTION_INPUT_ followed by the name of the action input to avoid collision with other environment variables. https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections
• Have a readme.md file in the action folder that explains the action and how to use it.
• Have a Action-Test workflow file that tests the action.
• Use the Auto-Release action for automating the release of the action via pull requeusts.
• Actions versions must be available as vX, vX.Y and vX.Y.Z tags, where they get the updates on their respective version.
  • vX automatically gets all the feature and patch updates until a breaking change is introduced.
  • vX.Y automatically gets all the patch updates until a new feature is introduced.
  • vX.Y.Z is locked to the exact version and will not get any updates.
• Older version of the action are not updates on their given track. i.e., if an older version of the action has bugs or a security issue,
  the fix will be implemented on the latest version and the user will have to update to the latest version to get the fix.

Configuration

• Actions should have parameters to configure the action with smart default values.
• Actions should also be able to take a configuration file as a yaml file, that is stored in the repository's .github folder.
• The configuration should also be able to be stored in the organizations .github repository, to simplify configuration control for all the repositories in the organization.
• The configuration should be called the name of the action/workflow and be a yaml file.
• Configuration precedence is as follows:
  1. Action inputs, over
  2. Repository configuration, over
  3. Organization configuration, over
  4. Action inputs default values.
• Configuration processing is as follows:
  1. Start with defaults from the action.
  2. Load the configuration from the organization .github repository, overwriting defined values only.
  3. Load the configuration from the repository .github folder, overwriting defined values only.
  4. Load the configuration from the action inputs, overwriting defined values only.

[MariusStorhaug]

Moving this to an issue on the PSModule/Docs repo