Make Github addon optional

.template/addons/github/.github/workflows/README.md.tt

@@ -70,4 +70,4 @@ Once all setup, give it a try by running manually the GitHub Action 'Deploy Hero
 - Set up the following GitHub repository secrets
   - GH_EMAIL (an email to identify the bot that publish the wiki content in the git history)
   - GH_TOKEN (the above generated token)
-- Creat a `.github/wiki` directory to store the documents to be published to Wiki.
+- Create a `.github/wiki` directory to store the documents to be published to Wiki.

.template/addons/github/template.rb

@@ -1,3 +1,24 @@
 use_source_path __dir__
 
 directory '.github'
+
+# Split README.md file to multiple wiki pages
+original_readme = File.read 'README.md'
+
+create_file '.github/wiki/Getting-Started.md' do
+  get_content_between(original_readme, "## Getting Started", "## Testing")
+end
+
+create_file '.github/wiki/Testing.md' do
+  get_content_between(original_readme, "## Testing", "## CI/CD")
+end
+
+FileUtils.mv '.github/workflows/README.md', '.github/wiki/CI-CD.md'
+
+gsub_file 'README.md', /## Getting Started.*/m do
+  <<~README
+    ## Documentation
+
+    Please check out full documentation on the [wiki](link to github wiki goes here).
+  README
+end

.template/spec/addons/base/github/template_spec.rb

@@ -5,19 +5,65 @@
 
   it 'creates Github actions workflows' do
     expect(file('.github/workflows/deploy_heroku.yml')).to exist
+    expect(file('.github/workflows/publish_wiki.yml')).to exist
+    expect(file('.github/workflows/review_code.yml')).to exist
     expect(file('.github/workflows/test_production_build.yml')).to exist
     expect(file('.github/workflows/test.yml')).to exist
   end
 
-  it 'creates Github wiki' do
+  it 'creates Github wiki structure' do
     expect(file('.github/wiki/_Sidebar.md')).to exist
     expect(file('.github/wiki/_Footer.md')).to exist
-
     expect(file('.github/wiki/Home.md')).to exist
-    expect(file('.github/wiki/Getting-Started.md')).to exist
-    expect(file('.github/wiki/CI-CD.md')).to exist
-    expect(file('.github/wiki/Testing.md')).to exist
-
     expect(file('.github/wiki/assets/images/.keep')).to exist
   end
+
+  xit 'modifies the README.md' do
+    expect(file('README.md')).to contain("## Documentation")
+
+    expect(file('README.md')).not_to contain("## Getting Started")
+    expect(file('README.md')).not_to contain("## Testing")
+    expect(file('README.md')).not_to contain("## CI/CD")
+  end
+
+  describe '.github/wiki/Getting-Started.md' do
+    it 'exists' do
+      expect(file('.github/wiki/Getting-Started.md')).to exist
+    end
+
+    it 'contains the correct content extracted from README.md' do
+      expect(file('.github/wiki/Getting-Started.md')).to contain("### Prerequisites")
+      expect(file('.github/wiki/Getting-Started.md')).to contain("### Docker")
+      expect(file('.github/wiki/Getting-Started.md')).to contain("### Development")
+    end
+  end
+
+  describe '.github/wiki/CI-CD.md' do
+    it 'exists' do
+      expect(file('.github/wiki/CI-CD.md')).to exist
+    end
+
+    it 'contains the correct content extracted from the workflow README.md' do
+      expect(file('.github/wiki/CI-CD.md')).to contain("## Test workflow")
+      expect(file('.github/wiki/CI-CD.md')).to contain("## Test production build workflow")
+      expect(file('.github/wiki/CI-CD.md')).to contain("## Deploy to Heroku workflow")
+      expect(file('.github/wiki/CI-CD.md')).to contain("## Publish to Wiki workflow")
+    end
+
+    it 'deletes the workflow README.md' do
+      expect(file('.github/workflow/README.md')).not_to exist
+    end
+  end
+
+  describe '.github/wiki/Testing.md' do
+    it 'exists' do
+      expect(file('.github/wiki/Testing.md')).to exist
+    end
+
+    it 'contains the correct content extracted from README.md' do
+      expect(file('.github/wiki/Testing.md')).to contain("### Docker-based tests on the CI server")
+      expect(file('.github/wiki/Testing.md')).to contain("### Test")
+      expect(file('.github/wiki/Testing.md')).to contain("### Automated Code Review Setup")
+    end
+  end
 end

Makefile

@@ -1,8 +1,9 @@
+# Y - in response to Would you like to add the Github addon?
 # Y - in response to Would you like to add the SemaphoreCI addon?
 # Y - in response to Would you like to add the Nginx addon?
 # Y - in response to Would you like to add the PhraseApp addon?
 # Y - in response to Would you like to add the Devise addon?
-common_addon_prompts = Y\nY\nY\nY\n
+common_addon_prompts = Y\nY\nY\nY\nY\n
 
 # Y - in response to Would you like to add the Bootstrap addon?
 # Y - in response to Would you like to add the Slim Template Engine addon?

README.md.tt

@@ -4,6 +4,120 @@
 
 > *App introduction goes here ...*
 
-## Documentation
+## Getting Started
 
-Please check out full documentation on the [wiki](link to github wiki goes here).
+### Prerequisites
+
+- Ruby version: <%= RUBY_VERSION %>
+<%- if WEB_VARIANT -%>
+- Node version: <%= NODE_VERSION %>
+<%- end -%>
+
+### Docker
+
+- Install [Docker for Mac](https://docs.docker.com/docker-for-mac/install/)
+
+- Setup and boot the Docker containers:
+
+```sh
+./bin/envsetup.sh
+```
+
+### Development
+
+- Setup the databases:
+
+  - Postgres:
+
+  ```sh
+  rake db:setup
+  ```
+
+- Run the Rails app
+
+```sh
+./bin/dev
+```
+
+## Testing
+
+### Docker-based tests on the CI server
+
+Add the following build settings to run the tests in the Docker environment via Docker Compose (configuration in `docker-compose.test.yml`):
+
+- Configure the environment variable `BRANCH_TAG` to tag Docker images per branch, e.g:
+
+```sh
+# a unique `BRANCH_TAG` value to tag the Docker image
+# e.g $SEMAPHORE_BRANCH_ID or using the
+# or using nimblehq/[email protected] Github action
+export BRANCH_TAG= # unique value for tagging Docker image
+```
+
+Each branch needs to have its own Docker image to avoid build settings disparities and leverage Docker image caching.
+
+> BRANCH_TAG must not contain special characters (`/`) to be valid. So using $BRANCH_NAME will not work e.g. chore/setup-docker.
+An alternative is to use a unique identifier such as PR_ID or BRANCH_ID on the CI server.
+
+- Pull the latest version the Docker image for the branch:
+
+```sh
+docker pull $DOCKER_IMAGE:$BRANCH_TAG || true
+```
+
+On each build, the CI environment does not contain yet a cached version of the image. Therefore, it is required to pull
+it first to leverage the `cache_from` settings of Docker Compose which avoids rebuilding the whole Docker image on subsequent test builds.
+
+- Build the Docker image:
+
+```sh
+./bin/docker-prepare && docker compose -f docker-compose.test.yml build
+```
+
+Upon the first build, the whole Docker image is built from the ground up and tagged using `$BRANCH_TAG`.
+
+- Push the latest version of the Docker image for this branch:
+
+```sh
+docker push $DOCKER_IMAGE:$BRANCH_TAG
+```
+
+- Setup the test database:
+
+```sh
+docker compose -f docker-compose.test.yml run test bin/bundle exec rake db:test:prepare
+```
+
+### Test
+
+- Run all tests:
+
+```sh
+# Docker way
+docker compose -f docker-compose.test.yml run test
+
+# Non-Docker way
+rspec
+```
+
+- Run a specific test:
+
+```sh
+# Docker way
+docker compose -f docker-compose.test.yml run test bin/bundle exec rspec [rspec-params]
+
+# Non-Docker way
+rspec [rspec-params]
+```
+
+### Automated Code Review Setup
+- Add a bot (i.e. `team-nimblehq`) to this repository or to the organization. The bot requires permission level “Write” to be able to set a PR’s status.
+
+- Create a [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)
+from bot account with `public_repo` scope, and set it as `DANGER_GITHUB_API_TOKEN` secret on the CI Environment Settings.
+
+## CI/CD
+
+The project relies entirely on [Github Actions](https://github.com/features/actions) for CI/CD via multiple workflows located under the [`.github/workflows/`](.github/workflows) directory.
+
+Please check out the [`.github/workflows/README.md`](.github/workflows/README.md) file for further instructions.

template.rb

@@ -15,8 +15,7 @@
 # Addons
 DEFAULT_ADDONS = {
   docker: 'Docker',
-  heroku: 'Heroku',
-  github: 'Github along with Github Action and Wiki'
+  heroku: 'Heroku'
 }.freeze
 
 if WEB_VARIANT
@@ -66,6 +65,7 @@ def apply_template!(template_root)
   post_default_addons_install
 
   # Add-ons - [Optional]
+  apply '.template/addons/github/template.rb' if yes?(install_addon_prompt('Github workflow and wiki'))
   apply '.template/addons/semaphore/template.rb' if yes?(install_addon_prompt('SemaphoreCI'))
   apply '.template/addons/nginx/template.rb' if yes?(install_addon_prompt('Nginx'))
   apply '.template/addons/phrase_app/template.rb' if yes?(install_addon_prompt('PhraseApp'))
@@ -138,6 +138,10 @@ def post_default_addons_install
   EOT
 end
 
+def get_content_between(content, string_start, string_end)
+  content[/#{Regexp.escape(string_start)}(.*)#{Regexp.escape(string_end)}/m, 1].strip
+end
+
 # Init the source path
 @source_paths ||= []