From ee23bb7911003bc6f91984bc8f1c484d00e8286b Mon Sep 17 00:00:00 2001 From: Remco de Boer Date: Tue, 24 Nov 2020 17:15:31 +0100 Subject: [PATCH] docs: describe epic branching model (#53) --- .gitignore | 2 + .pre-commit-config.yaml | 3 +- docs/_static/epic-branches.svg | 1 + docs/develop.md | 83 ++++++++++++++++++++++++++++++---- 4 files changed, 79 insertions(+), 10 deletions(-) create mode 100644 docs/_static/epic-branches.svg diff --git a/.gitignore b/.gitignore index c30a66c1..c3462ef8 100644 --- a/.gitignore +++ b/.gitignore @@ -50,3 +50,5 @@ pyvenv*/ !cspell.json !environment.yml !pyrightconfig.json + +!docs/_static/* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 084e38b4..19bb2935 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -19,7 +19,8 @@ repos: exclude: > (?x)^( cspell.json| - .*\.bib + .*\.bib| + .*\.svg )$ - id: mixed-line-ending - id: trailing-whitespace diff --git a/docs/_static/epic-branches.svg b/docs/_static/epic-branches.svg new file mode 100644 index 00000000..efecf866 --- /dev/null +++ b/docs/_static/epic-branches.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/develop.md b/docs/develop.md index 1383a001..055c7fa1 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -506,11 +506,11 @@ this before you submit a pull request. ## Collaboration -The source code of all related repositories is maintained with Git and -published through GitHub. We keep track of issues with the code, documentation, -and developer set-up with GitHub issues (see for instance -[here](https://github.com/ComPWA/PWA-pages/issues)). This is also the place -where you can +The source code of all related repositories is maintained with +[Git](https://git-scm.com) and [GitHub](https://github.com). We keep track of +issues with the code, documentation, and developer set-up with GitHub issues +(see for instance [here](https://github.com/ComPWA/PWA-pages/issues)). This is +also the place where you can [report bugs](https://github.com/ComPWA/PWA-pages/issues/new/choose). ### Issue management @@ -529,6 +529,71 @@ Publicly available are: - [Milestones](https://github.com/ComPWA/PWA-pages/milestones?direction=asc&sort=title&state=open): way to bundle issues for upcoming releases. +- [Releases](https://github.com/ComPWA/PWA-pages/releases) (see + {ref}`develop:Milestones and releases`) + +### Branching model + +While our aim is to maintain long-term, stable projects, +{ref}`PWA software projects ` are academic projects that +are subject to change and often require swift modifications or new features for +ongoing analyses. For this reason, we work in different layers of development. +These layers are represented by Git branches. + +![Epic branches](./_static/epic-branches.svg) + +#### `stable` branch + +Represents the _latest release_ of the package that can be found on both the +GitHub release page and on PyPI (see {ref}`develop:Milestones and releases`). +The documentation of the `stable` branch is also the default view +{ref}`you see on Read the Docs ` (RTD). See e.g. +[expertsystem.rtfd.io/en/stable](https://expertsystem.rtfd.io/en/stable). + +#### `master` branch + +Represents the upcoming release of the package. This branch is not guaranteed +to be stable, but has high {ref}`CI standards ` +and can only be updated through reviewed pull requests. The documentation of +the `master` branch can be found on RTD under "latest", see e.g. +[expertsystem.rtfd.io/en/latest](https://expertsystem.rtfd.io/en/latest). + +#### Epic branches + +```{margin} +The word ["epic"](https://www.atlassian.com/agile/project-management/epics) is +used in +[agile software development](https://en.wikipedia.org/wiki/Agile_software_development). +``` + +When working on a feature or larger refactoring that may take a longer time +(think of implementing a new PWA formalism), we isolate its development under +an 'epic branch', separate from the `master` branch. Eventually, this epic +branch is to be merged back into the master, until then it is available for +discussion and testing. + +Pull requests to an epic branch require no code review and the CI checks are +less strict. This allows for faster development, while still offering the +possibility to discuss new implementations and +{ref}`keeping track of related issues `. + +Epic branches can be installed through PyPI as well. Say that a certain epic is +located under the branch `epic/some-title` and that the source code is located +under +[https://github.com/ComPWA/expertsystem](https://github.com/compwa/expertsystem), +it can be installed as follows: + +```bash +python3 -m pip install git+https://github.com/ComPWA/expertsystem@epic/some-title +``` + +#### Feature branches + +The {ref}`develop:master branch` and {ref}`develop:epic branches` can be +updated through pull requests. It is best to create such a pull request from a +separate branch, which does not have any CI or code review restrictions. We +call this a "feature branch". + ### Commit conventions - Please use @@ -553,15 +618,15 @@ Publicly available are: [Epic](https://blog.zenhub.com/working-with-epics-in-github) and split up into smaller tasks. -- Before creating a pull request, run `tox`. See also {ref}`develop:Testing`. +- Before creating a pull request, run `tox`. See also {ref}`develop:Tox`. - Also use a [conventional commit message](https://www.conventionalcommits.org) style for the PR title. This is because we follow a [linear commit history](https://docs.github.com/en/github/administering-a-repository/requiring-a-linear-commit-history) and the PR title will become the eventual commit message. Note that a - conventional commit message style, as well as - {ref}`PR labels `, are - {ref}`enforced through GitHub Actions ` (see overview + conventional commit message style is + {ref}`enforced through GitHub Actions `, as well as a + check on {ref}`PR labels ` (see overview [here](https://github.com/ComPWA/PWA-pages/actions?query=workflow%3A%22PR+linting%22)). The corresponding configuration file is {download}`commitlint.config.js <../commitlint.config.js>`.