connorcarnes / pwshcloudflare Goto Github PK

mkdocs is deploying to cloudflare pages but it looks terrible, need to look at how to configure mkdocs

Description

• Auto generate table that includes Function, corresponding api operation and it's implementation status (example below). Status field should either be supported, link to relevant issue or TBD. TBD should link to relevant issue template.
• Add a note that highlights "supported" doesn't equal "completely implemented". Major functionality should be there but sometimes we don't implement every parameter etc. because it'd be too time consuming. But make an issue and we'll check it out!

• Create helper functions to scaffold new functions, test files, type files, etc.

Description

• Currently in the /Public folder there is one long list of functions:

\Public
Get-ResourceOne.ps1
Get-ResourceTwo.ps1
Set-ResourceOne.ps1
Set-ResourceTwo.ps1

• In similar projects I've seen developers group functions by folders. Example:

\Public
  \ResourceOne
    Get-ResourceOne.ps1
    Set-ResourceOne.ps1
  \ResourceTwo
    Get-ResourceTwo.ps1
    Set-ResourceTwo.ps1

• I haven't done this before but I think it'll keep the module more organized and I'm not aware of any drawbacks - need to investigate
• Here is an example of what I mean https://github.com/pcgeek86/PSGitHub/tree/master/Functions/Public

Get-CFAccount accepts a single name or id e.g. Get-CFAccount -Name 'accountName'. I know we can write the functions to handle multiple inputs e.g. Get-CFAccount -Name 'accountName1', 'accountName2' but I was getting side tracked wondering how I'd go about it. Specifically I was wondering if query params allow wildcards or multiple inputs

Description

• Tidy up mkdocs and deploy on cloudflrae pages. Make it so doc only updates trigger rebuild of pages site

This is the current Dockerfile:

FROM mcr.microsoft.com/devcontainers/base:ubuntu
# https://learn.microsoft.com/en-us/powershell/scripting/install/install-ubuntu?view=powershell-7.4
COPY bootstrap.ps1 bootstrap.ps1
RUN apt-get update \
    && apt-get install -y wget apt-transport-https software-properties-common \
    && wget -q https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb \
    && dpkg -i packages-microsoft-prod.deb \
    && rm packages-microsoft-prod.deb \
    && apt-get update \
    && apt-get install -y powershell \
    && pwsh -File bootstrap.ps1
COPY profile.ps1 /opt/microsoft/powershell/7/profile.ps1

It works fine so far but the below pseudo Dockerfile may be better:

FROM mcr.microsoft.com/devcontainers/base:ubuntu
# https://learn.microsoft.com/en-us/powershell/scripting/install/install-ubuntu?view=powershell-7.4
RUN apt-get update \
    && apt-get install -y wget apt-transport-https software-properties-common \
    && wget -q https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb \
    && dpkg -i packages-microsoft-prod.deb \
    && rm packages-microsoft-prod.deb \
    && apt-get update 
RUN pwsh -File <path_to_.devcontainer/bootstrap.ps1>
COPY profile.ps1 /opt/microsoft/powershell/7/profile.ps1

Desired outcome is that first RUN statement gets cached. It takes the majority of the build time but changes the least. Bootstrap.ps1 in second RUN statement changes frequently. Need to test as I'm not sure if updating bootstrap.ps1 would trigger a rebuild of the layer. CMD or ENTRYPOINT may be more appropriate than second RUN statement.

Additionally, current Dockerfile executes bootstrap.ps1 as root user. It might be better to have it execute as vscode user as that's the user available in the devcontainer.

test

Description

• I think the way it's currently done is atypical. After user auths with Set-CloudflareSession, the arg completers are automatically registered. I like this because it makes it easy to use tab complete to cycle through friendly names of resources instead of IDs. E.G. Get-CFAccount -AccountName MyAccountName or Get-CFAccount -AccountId abc123etc. It probably shouldn't happen automatically though. There's no advantage if module is run in automation and may affect performance if there's a ton of resources
• Alternative approach is to give user the option to auto register the completers via a param in Set-CloudflareSession. The value of this param should be saved in config/profile file as well.
• If user doesn't register the argument completers consider throwing warning that 1) states tab completion won't work 2) links to section of docs about arg completers/tab completion

Description

• Automate publishing to PSGallery
• Start writing integration/smoke tests.
  • Test different auth scenarios. What happens if endpoint requires a token but user is authed with key and vice versa?
• Need to review how others do this

Description

• I want to review the existing functions and their associated tests so that I can standardize them and make improvements if necessary.
• https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines?view=powershell-7.4#use-standard-parameter-names
• Normalize function prefixes or do away with them
• Evaluate if any code should be moved into a private function
• If any one function seems like it may take over an hour skip it and come back to it
• Take notes throughout the process to inform developer guidelines
• Goal is to get module ready for initial publish to PSGallery and create a contributor friendly project

Description

• explain dev environment and common patterns in project
  • use of types.ps1xml
  • arguement completers
  • Function naming convention: Get-CloudflareResource with alias Get-CFResource
  • specific on parameter names from this link (e.g. Get-Account should havhe -Name parameter and the parameter should have an alias of AccountName) https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines?view=powershell-7.4#use-standard-parameter-names
• write doc that walks someone through the process of setting up dev env and making PR start to finish.
• use of comments
• handling get and list endpoints as one function

Description

• At this point module should be tidied up. Functions and tests should be updated, all documentatoin updated, etc.
• Contributors should be able to pick these up and run with them
• I'm thinking a good approach is:
  • Create issue for endpoint/service. For example, R2. Issue name: Add Support for R2
  • Scope should be rather large, at least a function for New, Remove, Get and Set/Update/etc, associated tests, type file, argument completers, etc. Don't bother creating a bunch of issues up front, it's tedious and not sure it'll be worth the time.
  • Make it clear that if someone wants to contribute they don't have to take it all on at once. I'm happy to help with any of it and they're welcome to do as much or as little as they want.
  • As PRs are made we can check things off the scope, spin off new issues, etc.
  • Goal is to have a plan defined