Reformulate this Repository as a Base Repo: Collaborative-distributed-science-guide

[egrace479]

General Process/Tasks Outline

• Rename to Collaborative-distributed-science-guide
  • ALL links must point to new repo name location (e.g., questions comments and concerns at bottom of page, etc.)
    • These should be identified and identifiable for reuse—can this be encoded with a config? Otherwise find and replace through codebase.
• Add comments at personalization points (eg., logos, title, etc)
  • Specific files to update and guidance should be provided in the README as well
• Set shared logo
• Make shared code of conduct: combine the Code of Conduct (i.e., replace each instance of "Imageomics" with "Imageomics and ABC" or "Imageomics or ABC" as appropriate, since this is a shared space and the Code of Conduct for both are the same)
• Update homepage:
  • To have logo location with single shared logo? (<Organization> Branding (Logos) or Imageomics-ABC Branding (Logos), could include one of each?)
  • Explain background/history (as it does now up to generalization as base repo/template).
  • Collaborative Infrastructure We Use section—have both Institute and Center Code repositories (where Institute and Center get URLs)?
• Update citation with new name, v2.0.0, include Net, Graham, and Iuliia.
• Generate DOI on Zenodo for the Collaborative-distributed-science-guide through the GH integration (change name prior to release).
• Recommend adding the template/base repo as reference in CITATION.cff for forks? —We will do this for the Imageomics-guide and the ABC-guide
  • Shared Imageomics & ABC grant acknowledgment will be added to the repo README, as each site will just have its own acknowledgement in the footer.
  • Do we want to indicate our shared source repo on the websites themselves in some way (i.e., in the footer)?
• Add Imageomics-guide tag in repo before generalization point
• To-Do before generalization point:
  • Add in FAIR Guide section with checklists (PR Add FAIR Guide with Checklists #37)
  • Two bug fixes (Update .zendo.json instructions/references #14 & gh-pages branch protection rules in conflict with PR merge rules #21)

Proposed Method

The Imageomics-Guide needs to stay up during this process, so I propose the creation of a dev branch to work on the generalization. We will treat it as we do main, setting up branch protections and following the PR process to make the changes outlined above.

Specifically, I propose creating this new branch after merging PR #37, at which point I will add a tag to the commit. Once all changes are completed, rename and release has occurred, we will then create Imageomics-guide and ABC-guide forks on the respective GH Orgs to get the specific guides up and running.

Changes as follows:

• Replace all instances of "Imageomics-guide" with "Collaborative-distributed-science-guide" (equiv. "Imageomics Guide" --> "Collaborative Distributed Science Guide").
  • URLs and descriptions
  • Most URLs are relative links, but we have "Questions, Comments, Concerns"
• Set shared logo in mkdocs.yaml
• README: keep existing info with name update and add the following
  • Combined grant acknowledgement
  • Indicate which files should be updated/personalized (include comments in those files where appropriate, e.g., mkdocs.yaml title, logo, etc.)
  • Add any other information about suggested citation or acknowledgement---does this go into website somehow? The Imageomics and ABC guides will be a model, but good to be explicit in the README about what to do with this.
• Website homepage (docs/index.md):
  • Include links to both Imageomics and ABC collaborative infrastructure: "Imageomics and ABC Code Repositories" and "Imageomics and ABC Organization Pages"
  • Is there a desire to edit or remove the collaborative infrastructure diagram?
  • For the logos, do we want to have a single shared logo? (<Organization> Branding (Logos) or Imageomics-ABC Branding (Logos), could include one of each?)
• Why use the Institute GH & HF pages can both be changed to "why use our organization GH/HF" (alternatively, "the organization"), italics used to highlight difference only.
• Code of Conduct will be combined (i.e., replace each instance of "Imageomics" with "Imageomics and ABC" or "Imageomics or ABC" as appropriate).
• Update CITATION.cff to include Net, Iuliia, and Graham, will be v2.0.0 v1.0.0 on release---Imageomics Guide will go to v2.0.0.
• Add Digital Product Policies + landing page (explain as Imageomics versions, useful as template).
• Push dev branch to new Imageomics/Collaborative-distributed-science-guide repo.
• Revert all changes back to Imageomics-specific (still on dev), include also:
  • Removing ABC templates
  • Set acknowledgement back to just Imageomics grant in footer.
  • Update CONTRIBUTING.md to be just for Imageomics Guide and possibly include pointer to template for general updates.

Pages that have Imageomics-specific aspects to leave as they are:

• Digital Products Release Licensing Policy
• templates pages--have both Imageomics & ABC
• Infrastructure
• Glossary

[egrace479]

@gwtaylor, @hlapp, @ieyriay, @thompsonmj, I'd appreciate any and all feedback on this plan. I will be breaking the bullet points in the changes section of the Proposed Method into sub-issues.

[egrace479]

Spoke with @johnbradley about this plan. Addendum to avoid issues with GitHub auto-fix when repos are renamed, we should push the dev branch to a new repo, then these will have the same history and changing back to Imageomics-specific can be on that branch afterwards. The ABC-Guide will then be a fork.

[egrace479]

Discussing with @hlapp, we agreed it made most sense to set the Collaborative distributed science guide repo as a template repo. We can then provide instructions for those wishing to use it that there are two ways to do so and they should pick the one that makes most sense for their use-case and intentions downstream.

1. "Use this template" - will create a new repository (generated from the template repo) that does not share the commit history of the template. Updates could still be added from upstream, but this would require cherry-picking those commits.
2. "fork repo" - create a fork of the repo, then go into settings to change it to a normal repository instead of a template repo. This would allow for syncing upstream changes through the click of a button (as it would also preserve all commit history). We would add a caution of ensuring that PRs are pointed at the appropriate upstream.
   • Forking (and not changing from a template repo) would also be recommended for contributing to the upstream repo.

For the ABC-Guide, it would then be a question of how we wish to interact with the upstream for updates.

[egrace479]

Conversation with @gwtaylor and @ieyriay regarding ABC interaction. We agreed it makes the most sense to use the upstream template so that the ABC-Guide is not a fork. As core contributors, they would have access to the Collaborative distributed science guide repo for more direct edits and the ABC-Guide would just make use of the general updates, but not push back.

This is also consistent with how we wish to encourage use of the Collaborative distributed science guide repo to others: template is for building one's own, while a fork is for contributing back to the upstream when one doesn't have write access.

[hlapp]

Thanks @egrace479 for documenting the discussions that have been had. For the record, I'm on board with the plan as documented.