Decision Record (ADR) for profiles.yml directory search order

[dbeatty10]

Description

This PR is for an ADR. See #5411 and the ADR itself for a full description.

Checklist

• I have read the contributing guide and understand what's expected of me
• I have signed the CLA
• I have run this code in development and it appears to resolve the stated issue
• This PR includes tests, or tests are not required/relevant for this PR
• I have opened an issue to add/update docs, or docs changes are not required/relevant for this PR
• I have run changie new to create a changelog entry

[github-actions]

Thank you for your pull request! We could not find a changelog entry for this change. For details on how to document a change, see the contributing guide.

[leahwicz]

Discoverable/Accessible in what sense? Like inside your project?

[dbeatty10]

Yep, "discoverable/accessible" was intended to correlate with being "safe to store in GitHub".

[leahwicz]

I think you're right here so feel free to remove "(emphasis mine)"

[leahwicz]

Suggested change

	#### Approach 1
	#### Approach 1 (current approach)

[dbeatty10]

I intended to describe that both approach 1 and 2 are possible currently, and each are probably used frequently.

1 would be more likely to occur in a local environment.
2 is probably used most often in continuous integration (CI) environments.

I will re-work this section for clarity.

What I probably should have used as a guiding light instead:

• Categorizing as Approach A or Approach B entirely depends on if any secrets are in the profiles.yml file or not.

Whether there are any secrets depends whether it can be stored in VCS or not. Presence in VCS (or not) will then affect where the file is located within the file system.

[leahwicz]

@dbeatty10 thanks so much for making this!

I get a little lost going through this so let me list what I followed and then where it got blurry for me.

1. Initially, you describe the current behavior for how we look for certain yml files and then you propose a new search order. - I followed
2. Then list approaches to how to store properties and secret - I followed the approaches but got confused as to if these were current approaches people used today or if these were approaches you were proposing us to implement. I think these are current ways we can approach things today so maybe that could be clearer
3. Options section- from my perspective, you already have a solution because you listed it as the desired outcome above so it doesn't seem like the other outcomes are valid at this point. Does that make sense? Maybe move the desired outcome section down to the Decision section?

If you want, we can meet and chat about this if that's easier and this feedback isn't very clear.

[dbeatty10]

@leahwicz Your feedback is great! Thank you for outlining where it was clear and where it was unclear.

In my mind, there's five main topics to cover:

1. Current search order
2. Proposed search order
3. Current options for connection properties and connection secrets (two approaches)*
4. Listing of alternatives to the proposal (to proactively answer the question, "did you think about X instead?")
5. Pros and cons / tradeoffs of each alternative that was seriously considered

In my attempt to cover all of those, I think it got a bit confusing. Thanks to your feedback, I will try to reorganize for readability.

Probably the most confusing part was that while explaining the pros and cons of the two ways that profiles.yml can be used, I made it sound like these were options under consideration (when in fact, that was settled long, long ago).

*I wonder if it would be worth creating a stand-alone post-hoc ADR for the two ways that profiles.yml can be used (plain-text secrets vs. exclusively environment variables rather than plain-text secrets)?

[jtcohen6]

@dbeatty10 Is there any outstanding work here, or is it ready to be merged in? I'd love to have it in the repo, given the questions we've got from folks since the v1.3 release, which have largely been answered by the level of care and consideration you put into writing this up.

[github-actions]

This PR has been marked as Stale because it has been open with no activity as of late. If you would like the PR to remain open, please comment on the PR or else it will be closed in 7 days.

[github-actions]

Although we are closing this PR as stale, it can still be reopened to continue development. Just add a comment to notify the maintainers.