Sync `CONTRIBUTING.md`

[joshjohanning]

Like the other types of files we sync (dependabot.yml, workflows, copilot instructions) it would also be nice to sync the CONTRIBUTING.md file in the root of many OSS repos.

[Wuodan]

At this point I would think about a generic "make sure these files are in the repo" feature instead of individual files.

Example of implementation: User can define file-sets in folders, each set has its own root folder.
Then the action could just make sure all files below that set-folder (with recursion into subfolders) are in a target repository.

That would cover syncing any number of files.

---

This also would solve #119 and could possibly even replace setting dependabot.yml (or for dependabot the functionality could be re-used to avoid implementing file sync several times).

[joshjohanning]

👀 👀 👀

Ahh, this is pretty great. Like a map of source files to target files?

Old

  - repo: joshjohanning/azdo_commit_message_validator
    topics: 'github,actions,javascript,node-action,azure-devops,azure-boards'
    dependabot-yml: './config/dependabot/npm-actions.yml'
    rulesets-file: './config/rulesets/actions-ci.json'
    immutable-releases: true
    workflow-files:
      - ./config/workflows/ci.yml
      - ./config/workflows/publish.yml
    gitignore: './config/gitignore/.gitignore-actions'
    copilot-instructions-md: './config/copilot/copilot-instructions-actions.md'

New

  - repo: joshjohanning/azdo_commit_message_validator
    topics: 'github,actions,javascript,node-action,azure-devops,azure-boards'
    rulesets-file: './config/rulesets/actions-ci.json'
    immutable-releases: true
    files:
      - name: dependabot
        source: './config/dependabot/npm-actions.yml'
        target: '.github/dependabot.yml'
      - name: ci workflow
        source: './config/workflows/ci.yml'
        target: '.github/workflows/ci.yml'
        group: workflows
      - name: publish workflow
        source: './config/workflows/publish.yml'
        target: '.github/workflows/publish.yml'
        group: workflows
      - name: gitignore
        source: './config/gitignore/.gitignore-actions'
        target: '.gitignore'
      - name: copilot instructions
        source: './config/copilot/copilot-instructions-actions.md'
        target: '.github/copilot-instructions.md'

Same group == same PR (so if you are syncing 4 workflows it doesn't make 4 PRs!

Would have to get creative on the phrasing for the summary chart, but I think if we made the name property required I think this would work nicely!

Existing inputs like dependabot-yml, workflow-files, etc. could stay as convenient shortcuts since these are probably the most common to sync. But new file types (like CONTRIBUTING.md, .npmrc, SECURITY.md, etc.) would probably just use this files approach instead of adding a new dedicated input each time unless someone specifically requests for it.

[Wuodan]

My initial idea was to not even list individual files but to point to a parent folder and anything below is included.

Example of file template layout

Wuodan/sync-github-repo-settings is my repo running the bulk-github-repo-settings-sync-action action in a workflow.

So I would define a folder to hold such file configs, let's say ``.

Then below config/filesync I could define several file templates:

File Sync Templates

File Sync Template 1

config/filesync/template-1 contents

config/filesync/template-1/.gitignore
config/filesync/template-1/.github/dependabot.yml

File Sync Template 2

config/filesync/template-2 contents

config/filesync/template-2/foo/bar/myFile.txt
config/filesync/template-2/myFolder/someFile.yml

Target Repo to File Sync Config

Then for target repos A, B and C (or entire groups by selection) I would just point a the top template folder

repos:
  A:
    filesync: config/filesync/template-1
  B:
    filesync: config/filesync/template-1
  C:
    filesync: config/filesync/template-2

Result in target repos

The action would check each target repos for all files below a file-sync-template and open PR if they do not exist or
are different in the target repo.

So after the action and accepting the PRs, the target repos would have these files exactly as in their template:

Target repo A:

A/.gitignore
A/.github/dependabot.yml

Target repo B:

B/.gitignore
B/.github/dependabot.yml

Target repo C:

C/foo/bar/myFile.txt
C/myFolder/someFile.yml

[Wuodan]

Your approach of listing indiviual files per repo is also a valid solution.

It boils down to how you structure the configs of your repos and personal preference.

With your approach one will not have duplicate files but will have to make sure to have a correct mapping of source path and target path.

With my initial idea I will probably end up having duplicates of some files in several templates but can look at the folder structure in the file-sync templates as virtual roots of repos on GitHub with the folder structure I am used to.

In your approach I would probably have a structure similar to GH repos just to make it easier for me to manage it.

But then this starts being messy when I have several versions of one file, the fixed path of .github/dependabot.yml is such a case.

Here I then could either:

1. still have only one virtual .github folder and several dependabot.yml in it like:

config-root/.github/dependabot-1.yml
config-root/.github/dependabot-2.yml

and assign them by config to repos
2. or follow my original idea of having one root-folder per template group and thus stay close to target paths.

So probably even when following your approach of having to map all files individually I would probaly use template-roots and structure below at the cost of duplicating some files.

Reason: Easier to manage and understand. If I don't touch this for 6 months I will still easily understand it.

Plus my approach of just pointing at a template root folder scales much better: The complexity for many files to sync is not much higher.
With individual files this becomes hard to manage with many files.

---

So if I would slightly prefer the template-folder and everything below approach over the list individual files per target repo approach.

Not saying the other approach is not totally workable!

---

On a personal note: I enjoyed working on those projects/repos of yours in the last few days a lot. Thanks!

[Wuodan]

Possible extension of the file-sync-by-template-root idea:

We could potentially allow assigning several such template roots (for different categories) tgo one target repo.

Example from above:

Target Repo to File Sync Config

repos:
  A:
    filesync: config/filesync/template-1
    filesync: config/filesync/template-2

Here target repo A gets all files from 2 templates, the result in A would be:

A/.gitignore
A/.github/dependabot.yml
A/foo/bar/myFile.txt
A/myFolder/someFile.yml

We would have to define a strategy for conflict where a file is in 2 templates. Either error or last wins (with warning).
When there are 2 files but their contents are equal we could continue.

---

This is just an idea - I'm not sure it's a good idea yet though 😬

[joshjohanning]

On a personal note: I enjoyed working on those projects/repos of yours in the last few days a lot. Thanks!

<3

---

I haven't put much effort to this idea yet. I am more on the camp of the map as opposed to make this repo or dir look like the target, but, we could potentially support both.

👀 on the template approach