[MAINT] Proposal for adding ARCHITECTURE.md and MAINTERS.md

[deiga]

This PR proposes adding two new documentation files and updating the existing contributing guide to better serve contributors and maintainers:

ARCHITECTURE.md

A comprehensive implementation guide for contributors covering:

• Module map — project layout and file organization
• Core principles — one resource per API entity, minimize API calls, API-only operations
• Resource design — file naming, schema field guidelines, composite ID patterns (buildID/parseID2/parseID3/parseID4)
• Implementation patterns — context-aware CRUD signatures, API client access, error handling, state migrations (StateUpgraders), structured logging (tflog)
• Testing — test structure, test modes, running/debugging tests
• Gotchas & known issues — API preview headers, deprecated resources, known limitations, pending go-github updates
• Appendix — common utilities reference, naming conventions
• Decision log — records key architectural decisions with rationale (StateUpgraders, explicit auth, transport layer rework, no local git CLI, tflog migration, SDK v2 finalization)

MAINTAINERS.md

Lists current and emeritus maintainers with GitHub profile links.

CONTRIBUTING.md updates

• Added step for updating documentation when making changes
• Added step for ensuring formatting/linting passes
• Fixed markdown indentation for nested lists
• Replaced raw go test commands with make testacc T=... for consistency
• Updated debugging section to reference tflog migration pattern
• Removed hardcoded line-number GitHub permalink in favor of stable function name reference
• Added GITHUB_ENTERPRISE_SLUG environment variable

Code change

• Marked parseTwoPartID and parseThreePartID as @deprecated in github/util.go, pointing to parseID2/parseID3 replacements

Motivation

The provider currently lacks an architecture guide, making it harder for new contributors to understand conventions, patterns, and past decisions. These documents aim to:

1. Reduce onboarding friction for new contributors
2. Codify existing patterns so they're discoverable (not just tribal knowledge)
3. Record architectural decisions and their rationale
4. Establish a clear maintainer list

Discussion points

This is a proposal — feedback is welcome on:

• Content accuracy and completeness
• Whether any sections should be expanded, condensed, or reorganized
• Additional gotchas or known issues worth documenting
• Decision log entries that should be added or revised

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

[stevehipwell]

You probably need to add an allow for the linter?

[stevehipwell]

I think it'd be worth deprecating the build functions too?