Skip to content
Ed Ball edited this page Apr 24, 2023 · 15 revisions

Faithlife C# Template Project

Follow these steps to create a new project/repo based on the faithlife-build template. It is assumed that the project name has one or more periods, e.g., Faithlife.Xyz, and the repo name does not, e.g., FaithlifeXyz. In the instructions below, replace these terms with your project's/repo's name as appropriate.

Create a repository

  1. Create a new repository at https://github.com/Faithlife. (Don't initialize with any files.)
  2. In Settings, disable Wiki and Projects.
  3. Add team Faithlife/Coders with Admin permission.
  4. Add collaborator faithlifebuildbot with Write permission.

Clone the repository

git clone https://github.com/Faithlife/FaithlifeXyz.git
cd FaithlifeXyz

Fetch the template

git remote add template https://github.com/Faithlife/CSharpTemplate.git --no-tags -t faithlife-build
git fetch template

Merge the template

For a new repository with no commits:

git checkout -b master
git merge template/faithlife-build

For a repository with existing commits:

git merge --no-commit --allow-unrelated-histories template/faithlife-build

Modify the code and push to origin

dotnet tool update Faithlife.FindReplaceCode.Tool --global
findreplacecode . ProjectName Faithlife.Xyz RepoName FaithlifeXyz
git add -A
git commit -m "Replace template placeholders."
git push -u origin master

Set project description

  1. On the main repository page, provide a reasonable description.
  2. Change the description in README.md and Faithlife.Xyz.csproj to match.
  3. Consider adding matching tags to the repository and to Faithlife.Xyz.csproj.

Update repository settings

  1. In Settings, set GitHub Pages to master branch and /docs folder.
  2. On the repository home page, use https://faithlife.github.io/FaithlifeXyz/ as the website.
  3. Uncheck Releases, Packages, and Environments.

Integrate latest template changes

If the template changes in the future, it is easy to integrate into repositories that use it.

git fetch template
git merge --no-commit template/faithlife-build

Resolve any merge conflicts, run the test suite, etc. If everything passes, commit and push the changes.

Create new docs branch

Make sure you have no uncommitted changes, then:

git checkout --orphan docs
git clean -fdx
git rm -rf .
git merge --no-commit --allow-unrelated-histories template/faithlife-docs

Make necessary changes and push to origin.

In GitHub, open the repository settings and change Pages > Branch to docs, change the path to / (root), and hit Save.