Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,5 @@ node_modules
builds
package-lock.json
/resources
/public/**
/site/public/**
.hugo_build.lock
66 changes: 66 additions & 0 deletions docs/ADRs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Architecture Decision Records (ADR)

Here is where we log decisions we make about the architecture of the project.
Each decision will have it's own dedicated ADR file in this directory.

See the [Architecture Decision Record](https://github.com/joelparkerhenderson/architecture-decision-record) for more details of what an ADR is and common formats for it.

## Document format

The ADR file name should be prefixed with an incrementing, sequential number.
This shows the order in which decisions were made over the lifetime of the project.
e.g. `001-Use-ADRs-for-decisions.md`.

Here is an example of the sections that an ADR typically includes:

```markdown
## Status

What is the status, such as _proposed_, _accepted_, _rejected_, _superseded_, etc.? If _superseded_ by a subsequent decision, link to the subsequent decision. Include the date that the status change was made.

## Context

What is the issue that we're seeing that is motivating this decision or change? Are there any social or budgetary concerns that must be factored into the decision? Hyperlinks to supporting documentation are encouraged.

## Options Considered

What options are available to solve the aforementioned issue? What are the tradeoffs associated with each option? Hyperlinks to supporting documentation are encouraged.

## Decision

What is the change that we're proposing and/or doing to solve the aforementioned issue?

## Consequences

What becomes easier or more difficult to do because of this change? What are the immediate action items?

## References / Additional Reading

What individuals, teams, vendor documentation, and/or articles were consulted when gathering information throughout the decision-making process?
```

And an example of what an ADR might actually look like:

```markdown
# 001 - Record Architecture Decisions

## Status

Accepted 2022-10-28

## Context

As the project is an example of a more advanced monolith architecture, it is necessary to save all architectural decisions in one place.

## Decision

For all architectural decisions Architecture Decision Log (ADL) is created. All decisions will be recorded as Architecture Decision Records (ADR).

Each ADR will be recorded in the repository and contain following sections: __Status__, __Context__, __Options Considered__ (optional if decision is straightforward), __Decision__, __Consequences__, and __References / Additional Reading__ (optional, but strongly encouraged).

## Consequences

- All significant architectural decisions shall be recorded.
- Old decisions should be recorded with an approximate decision date where possible
- New decisions shall be recorded on a regular basis.
```
114 changes: 114 additions & 0 deletions docs/ADRs/001-2025-Aug-01-Initial.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
title: Initial
date: 2025-08-01
time: 07:05 UTC-0
attendees:
- '@kilasuit'
apologies:
- '@gaelcolas'
- '@johlju'
reviewers:
- '@gaelcolas'
- '@johlju'
outcome: Accepted
impactedAreas:
- Repo Layout
- Repo Scope
- Tech Used
---
<!-- markdownlint-disable MD025 -->
# 001 - Initial 2025-Aug-01

## Status

PartialDecision above 80%

See more in the Accepted , Declined & Deferred sections

## Context

As part of initial starting of a project we need to have a project structure along with a number of key decision points, like what technologies we are using and licensing to use.

We should also link to projects that have inspired this as to allow others to goforthwith and have a look at how they've done it.

We should also decide initial scope and what it means to be at a push publicly stage.

## Decision

### Decided by

@kilasuit - Ryan Yates

### Accepted

#### Use of ADR's

ADR's are useful to allow users, including maintainers, to comeback to a project and understand why decisions were made. These can be linked to in Issues, and in comments in code, allowing reviews at a later date.

ADR's can be either made public or kept private.

In this instance it was decided to make them public as part of the project & this initial ADR layout will be used in future projects as well.

#### Project Layout

As this is a project that will have multiple similar releasable artifacts, it was decided to have them all together in this repo.

This allows me to publish not only the extension packs, but also any extension if I were to build one in the future.

#### Documentation

Ideally this will follow a Just Enough Documentation model.

#### Project Scope

This project is for the DSC Community website and uses best practices for repo layout alongside tooling that help you with getting involved in this site.

#### Used Technologies

- VScode
- We use vscode as editor of choice for this repo

- GitHub
- We use GitHub to host the public version of this repo
- We use GitHub Issues, PR's and Projects
- We may use GitHub Actions in future

- Site Platform
- The Site Platform chosen is Hugo

- Virtual environments / devcontainers
- we have a devcontainer that can be used with this repo
- we also intend to publish a PowerShell DSC Configuration in this repo that can be used if you want this in a VM instead
- we also intend to publish a WinGet Configuration that can be used for setting up this repo & tooling in Windows (which may be used by DSC)

- Azure DevOps
- We may make use of Azure Repos for a secondary/private host of this repo
- We use Azure Pipelines for build and release
- We may synchronise Issues to Azure Boards...?

Public hosting
- This site is hosted at .....
- DNS for this site is managed by .....


- CoPilot/AI
- We will were we have access and where appropriate may make use of CoPilot/AI to help with this project.
- In any articles published that have been helped by AI, we will add the AI Used as a Co-Author


### Declined

None

### Deferred


### Notes

Awaiting input from @gaelcolas @johlju and others

### Historic Notes

This ADR is many years after the project started and whilst we could add an ADR starting `000-` this starts to serve as an initial starting place to help others understand this particular project.

### Updated
99 changes: 99 additions & 0 deletions docs/ADRs/ADR-Process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# ADR-Process

This documents the ADR Process we have in use (diagram to follow in future)

## Why

The Following is the Process and template that we will use for ADR's going forward

### FileName

The filename will be as follows `<Number>-<yyyy-MMM-dd>-<Reason<.md`

For example starting with `001-2025-Aug-01-Initial.md`

If there are mulitiple similar ADR's in a day, then we can either update the ADR, or add a seperate ADR, with preference to add a new one, as opposed to update an existing one as this can be used for additional learning opportunities & better documents how and why changes have been decided.

### Sample ADR

The below is a sample ADR Layout and all ADR's **must** contain the below sections

Time **must** be added like below (using UTC + offset) and date **must** use yyyy-MMM-dd

```
---
title: Initial
date: 2024-Dec-12
time: 07:05 UTC-0
attendees:
- @kilasuit
# apologies:
outcome: PartialDecision (>80%)
impactedAreas:
- Repo Layout
- Repo Scope
- Tech Used
---
<!-- markdownlint-disable MD025 -->
# 001 - 2024-Dec-12 - Initial

## Status

Accepted,Declined,Deferred

## Context

Add in any relevant context, for example any Issues/Discussions that are relevant.

## Discussed by
<!-- Add in any attendees, using thier handle/email address and their Name like below -->
@kilasuit - Ryan Yates

## Decision

### Accepted

#### Project Layout

As this is a project that will have multiple similar releasable artifacts, it was decided to have them all togeter in this repo.

#### Project Scope

This project will only have items relating to building/using vscode extensions.

It likely will include sample `.vscode` files, including sample VSCode Profile configurations.

#### Used Technologies

- VScode
- As this is a VSCode related repo we will use vscode and st
- GitHub
- We use GitHub to host the public version of this repo
- We use GitHub Issues, PR's and Projects
- We may use GitHub Actions in future
- Azure DevOps
- We make use of Azure Repos for a secondary host and the private version of this repo
- We use Azure Pipelines for build and release
- We intend to syncronise Issues to Azure Boards

### Declined

Declined publishing publically at this time

### Deferred

When to publish publically

### Notes

Add in any notes including comments made in the decison process

```

### Publishing ADR's

If a project needs to ADR's can be published to any staticially generated website.

### Reusing this process

The ADR process can also be used as a framework for publishing outcomes from meetings you may have as part of maintaining a project or across projects as part of a member of Working Groups
9 changes: 9 additions & 0 deletions docs/Contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Contributing to this project

Feel free to open an issue or pull request.


## Why was a specific decision made

Curious about some of the choices made in this project?
The reasons may be documented in the [ADRs folder](/docs/ADRs/).
7 changes: 7 additions & 0 deletions docs/InspiredBy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
## InspiredBy

This project has been inspired by many other sites out there.

The Layout of this repo has been inspired by the learnings that all the current and former maintainers have had over the years in WebSite & Software Development.

(Sample sites & projects that inspired this to come in a future post)
1 change: 0 additions & 1 deletion public
Submodule public deleted from 667ba1
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.