How to adopt the skeleton in an existing repo

If you have an existing repo and would like to adopt the skeleton structure then you can use the commandline tool to merge the skeleton into your repo:

dls-python3-skeleton existing /path/to/existing/repo

This will:

  • Take the repo name from the last element of the path

  • Take the package name from the repo name unless overridden by --package

  • Clone the existing repo in /tmp

  • Create a new orphan merge branch from the skeleton repo

  • Create a single commit that modifies the skeleton with the repo and package name

  • Push that merge branch back to the existing repo

  • Merge with the currently checked out branch, leaving you to fix the conflicts

Note

If you installed the commandline tool in a virtualenv, be sure to run deactivate when you have finished running it, otherwise pipenv install will use your virtualenv rather than making its own

Example merge

As an example, scanspec #46 shows the what this adoption looks like. The commandline tool was run on the existing repo:

$ cd /path/to/scanspec
$ git checkout -b adopt-skeleton
Switched to a new branch 'adopt-skeleton'
$ dls-python3-skeleton existing .
Auto-merging src/scanspec/__main__.py
CONFLICT (add/add): Merge conflict in src/scanspec/__main__.py
Auto-merging src/scanspec/__init__.py
CONFLICT (add/add): Merge conflict in src/scanspec/__init__.py
Auto-merging setup.cfg
CONFLICT (add/add): Merge conflict in setup.cfg
Auto-merging pyproject.toml
CONFLICT (add/add): Merge conflict in pyproject.toml
Auto-merging docs/tutorials/installation.rst
CONFLICT (add/add): Merge conflict in docs/tutorials/installation.rst
Auto-merging docs/reference/api.rst
CONFLICT (add/add): Merge conflict in docs/reference/api.rst
Auto-merging docs/index.rst
CONFLICT (add/add): Merge conflict in docs/index.rst
Auto-merging docs/conf.py
CONFLICT (add/add): Merge conflict in docs/conf.py
Auto-merging docs/_static/theme_overrides.css
CONFLICT (add/add): Merge conflict in docs/_static/theme_overrides.css
Auto-merging README.rst
CONFLICT (add/add): Merge conflict in README.rst
Auto-merging Pipfile
CONFLICT (add/add): Merge conflict in Pipfile
Auto-merging CONTRIBUTING.rst
CONFLICT (add/add): Merge conflict in CONTRIBUTING.rst
Auto-merging CHANGELOG.rst
CONFLICT (add/add): Merge conflict in CHANGELOG.rst
Auto-merging .vscode/settings.json
CONFLICT (add/add): Merge conflict in .vscode/settings.json
Auto-merging .vscode/launch.json
CONFLICT (add/add): Merge conflict in .vscode/launch.json
Auto-merging .github/workflows/docs.yml
CONFLICT (add/add): Merge conflict in .github/workflows/docs.yml
Auto-merging .github/workflows/code.yml
CONFLICT (add/add): Merge conflict in .github/workflows/code.yml
Auto-merging .gitattributes
CONFLICT (add/add): Merge conflict in .gitattributes
Automatic merge failed; fix conflicts and then commit the result.

Please fix the conflicts above, then you can run:
    git branch -d skeleton-merge-branch
Instructions on how to develop this module are in CONTRIBUTING.rst

First of the boilerplate files were removed:

$ git rm src/scanspec/hello.py docs/images/dls-logo.svg docs/images/dls-favicon.ico docs/how-to/accomplish-a-task.rst docs/explanations/why-is-something-so.rst -f
rm 'docs/explanations/why-is-something-so.rst'
rm 'docs/how-to/accomplish-a-task.rst'
rm 'docs/images/dls-favicon.ico'
rm 'docs/images/dls-logo.svg'
rm 'src/scanspec/hello.py'

Then the merge conflicts were fixed, and the pipenv dependencies updated:

$ pipenv --rm
$ rm Pipfile.lock
$ pipenv install --dev

The tests and docs were then run and checked:

$ pipenv run tests
$ pipenv run docs

Finally the results were committed, pushed, merged to master:

$ git commit
$ git push github adopt-skeleton
../_images/git_merge.png