php / php/doc-extensions

Discussion: What approach to use for migrating extensions

Open
#13 11 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
XML
Stars
2
Forks
6
Avg merge
1d 14h
Merged PRs (30d)
5

Description

Moving this out of php/doc-extensions#11 as it allows for a bit more room to plan strategy regarding migrating the extensions. And might reach a more broad audience.

First of all, what would be the very best method of migrating all extensions.
All in bulk with shared git commit history
Individually with git history
Don’t care about the git history

The primary reason we should preserve git history is to not lose the credibility that previous contributors have done over the years.

Migrating extensions individually would give the benefit of having a better understanding of what’s going on, and allow fixing what’s broken more easily but it will break those commits as some commits may have touched multiple extensions. Which is not the most positive outcome for existing contributors.

The suggested approach I have in mind is:

  • Migrate all extensions at once assuming it will break
  • See what's broken
  • Fix it (which likely will be DTD entities that we need to change to XML entities

Once that's done, I suggest we do a docbook-cs sweep so it will help contributors to make changes. We don't need to care about translators being overwhelmed by big changes.

Then finally we can prepare to publish this new doc-extensions repo by making a plan for:

  • Infastructure
  • Redirects
  • Etc, etc (will be a separate discussion once we are more ready for it).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with this strategy discussion and the originating php/doc-extensions#11 issue; no file or test is named. Review the proposed bulk migration, preservation of Git history, DTD-to-XML entity fixes, and docbook-cs sweep. Done means the migration approach is agreed and a follow-up plan covers infrastructure and redirects.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, xml
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.