chore: how to add a segment

CONTRIBUTING.md

@@ -2,12 +2,16 @@
 
 Note we have a code of conduct, please follow it in all your interactions with the project.
 
+Ensure you've read through the [documentation][docs] so you understand the core concepts of the
+project. If you're looking to get familiar with Go, following the [guide][guide] for adding
+segments can be a good starting point.
+
 ## Pull Request Process
 
 1. Ensure any dependencies or build artifacts are removed/ignored before creating a commit.
-2. Commits follow the conventional commits guidelines.
-3. Update the documentation with details of changes to the functionality, this includes new segments,
-   themes or core functionality.
+2. Commits follow the [conventional commits][cc] guidelines.
+3. Update the documentation with details of changes to the functionality, this includes new segments
+   or core functionality.
 4. Pull Requests are merged once all checks pass and a project maintainer has approved it.
 
 ## Code of Conduct
@@ -132,6 +136,9 @@ version 2.0, available [here][coc].
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
+[docs]: https://ohmyposh.dev/docs
+[guide]: https://ohmyposh.dev/docs/contributing-segment
+[cc]: https://www.conventionalcommits.org/en/v1.0.0/#summary
 [homepage]: https://www.contributor-covenant.org
 [conduct]: mailto:conduct@ohmyposh.dev
 [coc]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html

docs/docs/contributing-segment.md

@@ -0,0 +1,120 @@
+---
+id: contributing-segment
+title: Add Segment
+sidebar_label: Add Segment
+---
+
+## Create the logic
+
+Add a new file following this convention: `new_segment.go`.
+Ensure `new` is a single verb indicating the context the segment renders.
+
+You can use the following template as a guide.
+
+```go
+package main
+
+type new struct {
+    props          *properties
+    env            environmentInfo
+}
+
+const (
+    //NewProp switches something
+    NewProp Property = "newprop"
+)
+
+func (n *new) enabled() bool {
+    true
+}
+
+func (n *new) string() string {
+    newText := n.props.getString(NewProp, "n00b")
+    return newText
+}
+
+func (n *new) init(props *properties, env environmentInfo) {
+    n.props = props
+    n.env = env
+}
+```
+
+For each segment, there's a single test file ensuring the functionality going forward. The convention
+is `new_segment_test.go`, have a look at existing segment tests for inspiration.
+
+## Create a name for your Segment
+
+[`segment.go`][segment-go] contains the list of available `SegmentType`'s, which gives them a name we can map from the
+`.json` [themes][themes].
+
+Add your segment.
+
+```go
+//New is brand new
+New SegmentType = "new"
+```
+
+## Add the SegmentType mapping
+
+Map your `SegmentType` to your Segment in the `mapSegmentWithWriter` function.
+
+```go
+New: &new{},
+```
+
+## Test your functionality
+
+Even with unit tests, it's a good idea to build and validate the changes.
+
+```shell
+go build -o $GOPATH/bin/oh-my-posh
+```
+
+## Add the documentation
+
+Create a new `markdown` file underneath the [`docs/docs`][docs] folder called `new-segment.md`.
+Use the following template as a guide.
+
+````markdown
+---
+id: new
+title: New
+sidebar_label: New
+---
+
+## What
+
+Display something new.
+
+## Sample Configuration
+
+```json
+{
+  "type": "new",
+  "style": "powerline",
+  "powerline_symbol": "",
+  "foreground": "#193549",
+  "background": "#ffeb3b",
+  "properties": {
+    "newprop": "w00p"
+  }
+}
+```
+
+## Properties
+
+- newprop: `string` - the new text to show
+````
+
+## Map the new documentation in the sidebar
+
+Open [`sidebars.js`][sidebars] and add your document id (`new`) to the items of the Segments category.
+
+## Create a pull request
+
+And be patient, I'm going as fast as I can 🏎
+
+[segment-go]: https://github.com/JanDeDobbeleer/oh-my-posh3/blob/main/segment.go
+[themes]: https://github.com/JanDeDobbeleer/oh-my-posh3/tree/main/themes
+[docs]: https://github.com/JanDeDobbeleer/oh-my-posh3/tree/main/docs/docs
+[sidebars]: https://github.com/JanDeDobbeleer/oh-my-posh3/blob/main/docs/sidebars.js

docs/docusaurus.config.js

@@ -47,6 +47,10 @@ module.exports = {
               label: "Packages",
               to: "docs/powershell",
             },
+            {
+              label: "Contributing",
+              to: "docs/contributing",
+            },
           ],
         },
         {

docs/sidebars.js

@@ -29,5 +29,10 @@ module.exports = {
         "time",
       ]
     },
+    {
+      type: "category",
+      label: "Contributing",
+      items: ["contributing-segment"],
+    },
   ],
 };