Checklist for migrating an existing repository

[ncbaratta]

We need to add instructions on how to migrate an existing repository: https://redhat-documentation.github.io/community-collaboration-guide/#ccg-migrating-existing

[pmkovar]

This is going to be tricky to document because the instructions depend on the format and structure of a particular repo.

[ncbaratta]

I agree, I wonder if we should maybe vote next time on whether we need this in this particular guide or if it's outside of the scope.

[ncbaratta]

Per our meeting 1/9/18 - probably can't do this - but can write some tips for structures we see frequently. Could also be a checklist of items such as :

• are we in gitlab
• are we in github
• did we set up the attributes file
• etc.

[ncbaratta]

Possible titles:

• Checklist
• Preparation

Not exactly migration.

[pmkovar]

Cf. https://redhat-documentation.github.io/community-collaboration-guide/#ccg-checklist

[adahms]

@ncbaratta @pmkovar -

I have been doing a bit of thinking about this issue, and wanted to put a few thoughts to you both before going ahead and making any major changes.

First and foremost, I saw the main goal of this issue as providing some guidance to readers about how to move from an existing repository structure and workflow into the proposed repository structure and workflow. That I can do, and I'll have a draft before our meeting next week.

In thinking about that, however, I felt it might make more sense to add some content to other sections as well to help give readers a bit more context. To that end, I would like to propose the following -

• Add a few lines to 'Overview' to explain what is meant by setting up a new repository versus moving from an existing repository so that readers will know this guide covers these two main paths, and know where to find the relevant sections.
• Move 'Project Structure' under 'Creating a New Repository', add an introduction to the chapter that tells users that it explains how to set up things from scratch, and move the existing introduction to 'Setting up the Repository'. This chapter would guide users on how to set things up from scratch, including the major considerations such as where the repository would live and how it should be structured.
• Add a new chapter underneath the above called 'Moving from an Existing Repository' or similar that contains the checklist for moving from an existing repository and workflow. This chapter would guide users on how to set things up when they already have a downstream or upstream source, including the major considerations such as communicating the change and what changes they might need to make to the content so that it fits the structure.
• Move 'AsciiDoc', 'Building Content', and 'Publishing Content' under a single chapter called 'Managing Content' or similar so that these sections are positioned as additional things you need to think of regardless of whether you start from scratch or move from an existing repository.

I realize this is quite a big change, but if we want to provide guidance on these two paths, it feels like it would be good to help guide users through these decisions a little more across the board.

Happy to discuss during the upcoming meeting as well, and I'll have a go at a draft of some content for the considerations for review by then in case that helps demonstrate what I am thinking. :)

[pmkovar]

Move 'AsciiDoc', 'Building Content', and 'Publishing Content' under a single chapter called 'Managing Content' or similar so that these sections are positioned as additional things you need to think of regardless of whether you start from scratch or move from an existing repository.

Thanks Andrew. I think it all sounds fine, just not sure about the last point. Maybe instead of creating new top-level chapters with a deep navigation path, we could focus on creating separate index files with groups of topics (or assemblies, if you like) to support multiple navigation paths (or user stories), per #75.

I would probably start by making sure we have one section per file, which we can then include in multiple places.

[adahms]

@pmkovar - Thanks for the feedback, Petr!

It sounds like it might be a good idea to discuss this during the meeting. I have now submitted #93 as a first draft of some content for us to go over as well.

[pmkovar]

Based on the content submitted by @adahms, we could also add the following considerations to the checklist:

• different source format -- toolchain support, compatibility, conversions
• content licensing -- license compatibility, expectations, adding license notes

[ncbaratta]

Should we do a new Issue for this? Or just add it to this issue?

[pmkovar]

I don't think a new issue is necessary. Let's just keep this one open.

[adahms]

@ncbaratta @pmkovar - Thank you for your feedback.

I have now submitted #96 to add two paragraphs that provide some text on the two proposed topics. Maybe not a great amount of detail, but hopefully enough to let them make a start.

What do you think? I can see how we might add some more detail to them to provide more context, or is this sufficient for now?

[ncbaratta]

I think it's sufficient for now. I'd love to get some feedback from those working with communities and see if we can expand them based on experience.

[ncbaratta]

From meeting: Start making a list of things that other writers have done when they migrated their repositories - this will never be a comprehensive list due to the nature of differing repo structures