diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7dcd1beb..83479769 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -7,6 +7,7 @@ are two sorts of contributions: - Changes to the skeleton structure should be made on a branch of the skeleton-repo_ with a PR raised back to the ``main`` branch from here: PR_. + see `Skeleton` for more details. - Changes to the docs or commandline tool should be made on a branch in the cli-repo_ with with a PR raised back to the ``main`` branch here: PR2_ @@ -145,6 +146,7 @@ When this happens: - Choose ``Draft New Release`` - Click ``Choose Tag`` and supply the new tag you chose (click create new tag) - Click ``Generate release notes``, review and edit these notes +- If this is a pre-release then check the ``This is a pre-release`` check-box. - Choose a title and click ``Publish Release`` Note that tagging and pushing to the main branch has the same effect except that diff --git a/docs/explanations.rst b/docs/explanations.rst index 8c0a3b90..8bfa6a30 100644 --- a/docs/explanations.rst +++ b/docs/explanations.rst @@ -11,5 +11,5 @@ Explanation of how the library works and why it works that way. explanations/why-use-skeleton explanations/why-src explanations/why-pre-commit - explanations/features explanations/decisions + explanations/skeleton diff --git a/docs/explanations/features.rst b/docs/explanations/features.rst deleted file mode 100644 index 5c350790..00000000 --- a/docs/explanations/features.rst +++ /dev/null @@ -1,38 +0,0 @@ -Feature Update History -====================== - -August 18th 2022 ----------------- - -.. _CLI: https://epics-containers.github.io/python3-pip-skeleton-cli/ -.. _skeleton: https://epics-containers.github.io/python3-pip-skeleton/ - -- Project split into 2 repos - - - this project CLI_ provides this documentation and the code for adopting - skeleton - - the skeleton_ project provides the template source for adoption - - this avoids the confusion of using two 'main' branches in a single repo - - it also allows for separate github settings for the CLI and skeleton as - follows: - - - TODO list github branch and PR settings - -- Now allow CI to run on all branches but avoid duplicate CI runs using - https://github.com/marketplace/actions/skip-duplicate-actions -- Now use non-editable pip install for tests that do not use requirements.txt - - - This verifies that the packaging is working - -- the --org option when adopting is now mandatory to avoid accidentally - creating a repo for the default org. -- moved 'contributing.rst' from reference to how-to meaning that we no - longer require a dummy how-to article -- removed example code hello.py meaning that this does not - have to be deleted after adopting. Also removed related tests. -- Skeleton README reduced to remove example code and to point at - skeleton-cli for instructions. -- Github PR Policy set to rebase only for skeleton and any for cli. This is - to remove any commit hashes from commit comments. If these are present then - github will add incorrect comments to the target repo. - \ No newline at end of file diff --git a/docs/explanations/skeleton.rst b/docs/explanations/skeleton.rst new file mode 100644 index 00000000..1567fcb9 --- /dev/null +++ b/docs/explanations/skeleton.rst @@ -0,0 +1,81 @@ +.. _Skeleton: + +Working on the Skeleton Repo +============================ + +The python3-pip-skeleton_ repo has a protected main branch and is restricted to +rebase PRs only. +It is also squashed occasionally so some careful procedures are required. + +.. _python3-pip-skeleton: https://github.com/epics-containers/python3-pip-skeleton + +main +---- + +This branch is what all adopters of the skeleton project merge from so needs +to be kept tidy. +In particular it must not have any #nnn which would refer to the wrong commit +when merged into other repos (and github will see them and add incorrect +messages in PRs and Issues). This branch is protected from push and +restricted so that it can only be updated by a PR with REBASE. + +dev-archive +----------- +This branch to tracks all commits, including those that are squashed out of +main. Force push is disallowed on this branch so that it can be kept as a +safe record of the history. + +Process for making a change +--------------------------- +To make changes. First take a new branch off of main, make your changes +and do a pull request to rebase main on the branch. + +- get a branch on main + + - git checkout main + - git reset --hard origin/main # because main may have been rebased + - git checkout -b feature +- Do the changes and test in CI with: + + - git add --all + - git commit -m'my changes' + - git push -u origin feature +- When happy with changes use PR to rebase main on feature. +- Next delete feature: + + - git push origin :feature + - git checkout main + - git branch -fd feature + + +Process for squashing main +-------------------------- + +Once a year or so tidy up the history of main to make new adoptions easy. +Otherwise multiple changes to the same line in the history may cause multiple +merge conflicts on that line during re-merge of skeleton into projects +that have already adopted. + +Perform these steps + +- Get the dev-archive branch to remember your main commits + + - git checkout dev-archive + - git merge main +- If there are conflicts + + - git checkout --theirs + - git add --all + - git commit # the commit message will be 'merged ...' you can + add to it if needed +- Now squash main right back to the original ededf000 + - git checkout main + - git reset --hard /origin/main + - git rebase -i ededf000 + - In the rebase edit screen replace all ``pick`` with ``s`` except the first + one. save and quit +- Now create a handoff branch + - git checkout dev-archive + - git checkout -b handoff/202x-xx-xx + - git merge main + - git push -u origin handoff/202x-xx-xx diff --git a/src/python3_pip_skeleton/__main__.py b/src/python3_pip_skeleton/__main__.py index 99128648..481e5ce1 100644 --- a/src/python3_pip_skeleton/__main__.py +++ b/src/python3_pip_skeleton/__main__.py @@ -23,6 +23,7 @@ IGNORE_RANGES = { "CONTRIBUTING.rst": ("\nUpdating the tools\n", None), } + SKELETON_ROOT_COMMIT = "ededf00035e6ccfac78946213009c1ecd7c110a9"