Align CAMARA repositories on LF line endings and define migration path for existing repositories

[hdamker]

Problem description
Line ending handling is currently not defined consistently across CAMARA repositories. This allows CRLF to be introduced again depending on editor settings and operating system defaults, and it can also create cosmetic diffs in generated or normalized artifacts.

For new repositories, the expected direction is clear:

• add .editorconfig to guide editor behavior
• add .gitattributes to enforce line endings at the Git layer
• include both files in Template_API_repository

The open question is how to migrate and align existing repositories in a controlled way. This is especially relevant now, because most Fall25 repositories have not yet started their Sync26 work, so there is still a good window for a coordinated cleanup campaign with limited disruption.

Possible evolution
Define a CAMARA-wide LF policy for text files and implement it in two places:

• .editorconfig for editor-side defaults
• .gitattributes for repository-side enforcement

For new repositories:

• update Template_API_repository to include both files by default

For existing repositories:

• run a migration campaign across the relevant Fall25 repositories before Sync26 work starts
• ensure migration PRs are limited to line-ending policy and normalization only, with no functional changes mixed in

Two rollout options are possible:

Option 1: two PRs per repository

• PR 1 adds .editorconfig and .gitattributes
• PR 2 performs line-ending normalization only

Pros:

• cleaner review separation between policy introduction and file normalization
• easier to explain and audit
• lower risk if maintainers want to validate the policy before mass file changes

Cons:

• doubles the number of PRs to prepare, review, and merge
• extends the campaign duration
• may create extra coordination overhead across many repositories

Option 2: one centrally prepared PR per repository combining policy + normalization

• add .editorconfig and .gitattributes
• include the normalization changes in the same PR

Pros:

• faster rollout with fewer PRs overall
• less administrative overhead for the campaign
• each repository is aligned in a single step

Cons:

• larger diffs that may be harder to review
• more likely that GitHub shows files as broadly replaced because of line-ending changes
• policy definition and normalization are coupled, so review is less granular

Alternative solution
Do not run a migration campaign for existing repositories and only update Template_API_repository for future repositories.

This would improve the baseline going forward, but it would leave existing repositories inconsistent and would not reduce the chance of CRLF-related churn in current maintenance and release flows.

Additional context
A practical implementation detail is that .gitattributes should be treated as the authoritative enforcement mechanism, while .editorconfig is supportive and helps contributors avoid introducing CRLF during editing.

Proposed baseline .gitattributes content:

* text=auto eol=lf

*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.pdf binary
*.zip binary

This would make LF the default for text files in the repository. Binary files should be marked as binary so Git does not attempt end-of-line normalization.

If normalization is performed, the resulting PRs should contain only line-ending related changes. Reviewers should be informed that these are non-functional changes and may want to use whitespace-insensitive diff views.

[rartych]

Binary files should be marked as binary so Git does not attempt end-of-line normalization.

It happens that MS Office files are included as additional documentation (I have seen at least a few .pptx)

BTW, there was a proposal to slim down the release artifacts size by adding:
/documentation/MeetingMinutes export-ignore
to .gitattributes

[Kevsy]

Binary files should be marked as binary so Git does not attempt end-of-line normalization.

It happens that MS Office files are included as additional documentation (I have seen at least a few .pptx)

@rartych any idea how to search for unwelcome binary files?

I've tried e.g

org:camaraproject path:**/*.pptx

...which returns nothing, even though there are PPTX files e.g. here

The wildcard recursive directory search only seems to work for text files, e.g.
org:camaraproject path:**/*.yaml or org:camaraproject path:**/*.md returns all the YAML and MD in the repositories, even when deeply nested.

@hdamker I think I prefer Option 1 but it depends on the level of additional duration/complexity (and whether that can be solved by further automation)

[mohdfarhanakram]

+1 for Option 1 — keeping policy and normalization in separate PRs makes it much easier to review and roll back if something goes wrong.

@Kevsy for the binary file search — GitHub code search doesn't index binary files, which explains why the wildcard path query comes up empty. I found that the Git Trees API works as a workaround:

for repo in $(gh api "orgs/camaraproject/repos?per_page=100&type=public" --paginate --jq '.[].name'); do
  gh api "repos/camaraproject/$repo/git/trees/main?recursive=1" --jq '.tree[].path' 2>/dev/null \
    | grep -iE '\.(pptx|docx|xlsx|png|jpg|jpeg|gif|pdf|zip)$'
done

Ran this across all 91 repos — found binary files in 26 of them:

Extension	Approx count	Example repos
.pdf	80+	Governance, KnowYourCustomer, Marketing
.pptx / .PPTX	40+	WorkingGroups, CarrierBillingCheckOut, EdgeCloud
.png	50+	Governance, Commonalities, EasyCLA
.jpg / .jpeg	5	APIBacklog, NumberVerification
.docx	4	Marketing, Commonalities

Based on this, the .gitattributes binary list could look like:

*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.pdf binary
*.zip binary
*.pptx binary
*.docx binary
*.xlsx binary

One thing to note — there are a few uppercase extensions like .JPG and .PPTX in some repos. Git's .gitattributes matching is case-sensitive on case-sensitive filesystems, so might be worth adding those or relying on * text=auto for detection.

Happy to share the full per-repo list or pick up some normalization PRs once the approach is agreed.

[mohdfarhanakram]

Added a .gitattributes file as part of #112 under workspace-config/. It covers:

• text=auto eol=lf for LF normalization
• Binary markers for png, jpg, pdf, pptx, docx, xlsx, etc.
• export-ignore for /documentation/MeetingMinutes (per @rartych 's suggestion)

@hdamker Once the placement is agreed in #112, happy to help with the normalization migration PRs for existing repos.

[hdamker]

@hdamker Once the placement is agreed in #112, happy to help with the normalization migration PRs for existing repos.

@mohdfarhanakram thanks for the contributions. if the final content is agreed the bulk campaign will be run centrally via project-administration, not via individual PRs.