Introduce a develop branch

[dennisdoomen]

@bkoelman didn't we discuss to introduce a develop branch so that changes only become visible on the website after we release the changes?

[bkoelman]

Yes, we discussed that a while ago in #165.

Since that discussion, my point of view has changed a bit: I now believe its quite common for master to represent a "working" / "consistent" version, instead of match the latest released version.

The downside of having multiple branches is the limited ability to search on GitHub, which does not take non-default branches into account, as well as the added complexity for occasional contributors who now need to choose the right base branch. Having multiple branches brings up the question again what the default branch should be: choosing master will also make that the default PR target, which we'd like to avoid. Choosing develop as default branch effectively results in nobody looking at master anymore, so what's the point of having both?

While adding a develop branch increases release flexibility, we generally don't run into the problem that we need to release hotfixes that exclude recent changes from master. So in that sense, adding a develop branch would introduce unneeded complexity. Even in the unlikely case of hotfixes, we could always branch off a release tag and release from there.

If our goal is to ensure that https://www.csharpcodingguidelines.com/ only reflects the latest release, I think the easiest solution would be to keep a single branch, but make publishing the website conditional on drafting a new release (example here). Conceptually, publishing the website sounds similar to publishing a stable NuGet package, so I think we should align with that workflow.

[dennisdoomen]

I think the easiest solution would be to keep a single branch, but make publishing the website conditional on drafting a new release (example here).

That isn't possible. It's driven by Github directly.

[bkoelman]

Can you provide some more details on how that works?

[dennisdoomen]

There's not much you can configure.

[bkoelman]

I still think this should be possible. We use the following settings in JsonApiDotNetCore (note the source branch is gh-pages), combined with this script to push to the gh-pages branch on non-PR commits.

[dennisdoomen]

Wow. That's a pretty complicated process. It's doable, but I don't think it's worth my time right now.

[bkoelman]

It looks more complicated than it is. The git username/email don't actually exist, it is solely used for the commit history. I didn't want to put my personal email there for spamming reasons. All it does is fetch the branch, replace its contents and push. The crlf settings are probably not needed, as git has sensible defaults these days. Line breaks don't matter much anyway as the website is HTML. You'll need to create a GitHub token once (see link) and store that in a cibuild variable, to prevent just anyone from publishing the website.

[dennisdoomen]

I guess we can make that work using a nice Nuke script.

[bkoelman]

It's now pretty easy with GitHub Actions. All you need is something along the lines of:

name: Build

on:
  push:
    branches: [ 'master' ]
  pull_request:
    branches: [ 'master' ]
  release:
    types: [published]

jobs:
  build-and-test:
    # Regular build/test/package steps here...

  publish:
    runs-on: ubuntu-latest
    needs: [ build-and-test ]
    if: ${{ !github.event.pull_request.head.repo.fork }}
    permissions:
      contents: write
    steps:
    - name: Publish to GitHub Pages
      if: github.event_name == 'release'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_branch: gh-pages
        publish_dir: ./documentation