search

StackExchange / dnscontrol

Infrastructure as code for DNS!
https://dnscontrol.org/
MIT License
3.01k stars 378 forks source link

DOCS: M365_BUILDER() (Microsoft 365 builder) #3008

Open cafferata opened 3 weeks ago

cafferata commented 3 weeks ago

The example in the docs is wrong. apparently you need to pass the domain as first argument and the other options as second argument https://github.com/StackExchange/dnscontrol/blob/v4.11.0/pkg/js/helpers.js#L1709

Originally posted by @Koopzington in https://github.com/StackExchange/dnscontrol/issues/2457#issuecomment-2165769432

cafferata commented 3 weeks ago

@juliusrickert could you please tell us how you envisioned the M365_BUILDER() https://github.com/StackExchange/dnscontrol/commit/08cdba4a799d43b12425f2196cba9432474a76d3 and update the documentation?

juliusrickert commented 3 weeks ago

@juliusrickert could you please tell us how you envisioned the M365_BUILDER() 08cdba4 and update the documentation?

tl;dr I can't tell anymore and won't update the documentation, sorry.

Honestly, I didn't envision anything for M365_BUILDER as far as I can remember. Here's what I think to remember about the timeline:

I opened #1023 because I created a helper for my personal use and thought others might be in the same situation. I believed that a community-managed version of this helper would better suit everyone.

After publishing said helper, I was encouraged to submit it to the project, which I did in #2365. For my use cases, it was working well.

It was never my intention to support others in using the helper; I just wanted to help others by providing what works for me. Today, I don't use M365 anymore, and I forgot about most of its quirks. Likewise, I don't remember the hows and whys of my implementation.

In retrospect, I should have been more clear about my intentions.

juliusrickert commented 3 weeks ago

From the code, I deduce that the label must be provided as the first argument, named name, while the documentation states that it must be passed with the object in the first argument (which is, in fact, the second argument).

tlimoncelli commented 3 weeks ago

@juliusrickert Thank you for the timeline.

I appreciate your contribution and apologize that it turned into a support issue. I pushed you to include it in the project.

In hindsight, we (the project) should have a better process around such things. For example, we should probably just have a directory of sample macros/functions that people can view and learn from, and only adopt them into helpers.js on a case-by-case basis.

For M365_BUILDER(), we should update the docs to clarify that this macro isn't fully supported, encourage people to copy it into their own dnsconfig.js if the use it, and set a sun-set date.

cafferata commented 3 weeks ago

tl;dr I can't tell anymore and won't update the documentation, sorry.

@juliusrickert thank you for your quick and, above all, clear explanation. This benefits everyone! Out of interest, are you still using DNSControl (without Microsoft 365)? ☺️

I opened https://github.com/StackExchange/dnscontrol/issues/1023 because I created a helper for my personal use and thought others might be in the same situation. I believed that a community-managed version of this helper would better suit everyone.

For what it's worth; I've struggled with this idea a lot too. And every time I came to the conclusion that this was too personal. Or it became too global with 101 configuration options, which missed out on personal use.

My examples:

For example, we should probably just have a directory of sample macros/functions that people can view and learn from

I think this makes a lot of sense! This way, knowledge can still be shared without the need for long-term maintenance and/or breaking changes on a third-party helper like Microsoft 365.