diff --git a/.template/addons/github/.github/wiki/CI-CD.md b/.template/addons/github/.github/wiki/CI-CD.md deleted file mode 100644 index bb7f6d05..00000000 --- a/.template/addons/github/.github/wiki/CI-CD.md +++ /dev/null @@ -1,3 +0,0 @@ -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. diff --git a/.template/addons/github/.github/wiki/Getting-Started.md.tt b/.template/addons/github/.github/wiki/Getting-Started.md.tt deleted file mode 100644 index 5be3f87e..00000000 --- a/.template/addons/github/.github/wiki/Getting-Started.md.tt +++ /dev/null @@ -1,32 +0,0 @@ -### 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 -``` diff --git a/.template/addons/github/.github/wiki/Testing.md b/.template/addons/github/.github/wiki/Testing.md deleted file mode 100644 index bbfa9ef6..00000000 --- a/.template/addons/github/.github/wiki/Testing.md +++ /dev/null @@ -1,74 +0,0 @@ -### 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/branch-tag-action@v1.2 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. diff --git a/.template/addons/github/.github/workflows/README.md.tt b/.template/addons/github/.github/workflows/README.md.tt index 5a7b4974..2c9a2dd5 100644 --- a/.template/addons/github/.github/workflows/README.md.tt +++ b/.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. diff --git a/.template/addons/github/template.rb b/.template/addons/github/template.rb index cd163e30..22e8d952 100644 --- a/.template/addons/github/template.rb +++ b/.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 diff --git a/.template/spec/addons/base/github/template_spec.rb b/.template/spec/addons/base/github/template_spec.rb index a5f4f39c..f68f03b6 100644 --- a/.template/spec/addons/base/github/template_spec.rb +++ b/.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 diff --git a/Makefile b/Makefile index cdbe841d..2f08dcf8 100644 --- a/Makefile +++ b/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? diff --git a/README.md.tt b/README.md.tt index d9d2799a..88a215ff 100644 --- a/README.md.tt +++ b/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/branch-tag-action@v1.2 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. diff --git a/template.rb b/template.rb index a8a8ada5..be172a52 100644 --- a/template.rb +++ b/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 ||= []