The Common Project Template

A common project template to start of, batteries included.

https://gitlab.com/the-common/project-template

How to use

If you're on GitLab

1. Create a new project via the on-site interface, it is required to check the "Initialize repository with a README" checkbox.

2. At localhost, launch a text terminal application, and run the following commands to clone the new project's repository to local:

   git clone \
       _repository_url_ \
       _project_directory_

3. Downloading a copy of The Common Project Template release archive

4. Extract The Common Project Template release archive to a temporary directory

5. Copy all the files to the new project local repository's working tree

6. Continue the operation in Common instructions

If you're on GitHub

1. Click the "Use this template" green button on the mirrored GitHub project page
2. Follow the instructions on the webpage to create a new project
3. Continue the operation in Common instructions

Common instructions

1. Rename the following files to have the real project files in their intended place:

   • real.README.md→README.md
     This is the real project README document, which is renamed to make place for the project template README.
   • real.gitattributes→.gitattributes
     This is the real Git path attributres configuration file, which is renamed to ensure all template files are included in the template release archive.
   • real.markdownlint.yml→.markdownlint.yml
     This is the real Markdownlint configuration file, which is renamed as it's no-emphasis-as-heading linting rule will not work for the real version of the project README document.

2. Edit the README.md project README template, replace the following `placeholders to the appropriate content:

   • _project_name_
     The (display) name of the project.
   • _project_summary_
     A one-line summary of the project.
   • _namespace_/_project_
     The variable part of the project URL, you use another project hosting service you need to manually replace the entire URL instead.
   • _license_name_
     The name of the main license of the project.
   • _license_url_
     the URL of the main license of the project.

3. Replace the project-name placeholder text in the compose.yml Compose configuration file to your project's hostname-friendly name.

4. Customize/remove Telegram notification details in .github/workflows/check-potential-problems.yml

5. Run the following commands(or its equivalent operation) to remove the template-only custom license:

   find_opts=(
       -type f
       -exec
           sed
               --in-place
               --regexp-extended
               --expression='s@ OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects@@g'
               {}
               ';'
   )
   find . "${find_opts[@]}"
   rm -f LICENSES/LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects.txt

6. (OPTIONAL) Running the following command to setup the pre-commit hook for the pre-commit framework:

   pre-commit install

7. Commit all changes as a new revision(commit summary for reference: docs: Write project README prototype)

8. (If you've cloned the repository back to local) push local changes to the remote repository

(OPTIONAL) Setting up Telegram notifications on GitLab

Refer to the following instructions to set up Telegram notifications on changes of the project on GitLab:

1. From the project page, select the Settings > Integrations option in the menu.
2. Click the Add button at the right of the Telegram option in the Add an integration panel.
3. Toggle the Active checkbox in the Enable integration field.
4. Fill in your Telegram bot token(can be obtained from the @BotFather Telegram channel).
5. Selecting events that you want to trigger the Telegram notifications
6. In the Notification settings section:
   1. Set the channel identifier where you want the Telgram bot to send notification to in the Channel identifier field.
   2. (OPTIONAL) Untoggle the Notify only broken pipelines checkbox in the Notify only broken pipelines field so that you'll also be notified of successful pipelines.
   3. (OPTIONAL) In the Branches for which notifications are to be sent dropdown menu, select All branches so that notifications from all branches will be sent to the specified Telegram channel.
7. Click the Test settings button at the end of the form to verify whether the Telegram notification can be sent.
8. Click the Save changes button at the end of the form to apply the changes.

(OPTIONAL) Setting up Telegram notifications on GitHub

Refer to the following instructions to set up Telegram notifications on changes of the project on GitHub:

1. From the project settings page, select Security > Secrets and variables > Actions in the menu to open the corresponding page.
2. In the Repository secrets panel of the Secrets tab, click the New repository secret button at the top-right.
3. Enter telegram_bot_api_token_ci in the Name field, then paste in your Telegram bot token to the Secret field.
4. Click the Add secret button at the bottom of the form to apply the changes.

(OPTIONAL) Setting up GitLab to GitHub mirroring

Refer to the following instructions to set up automatic mirroring of the GitLab repository to GitHub:

1. (IF NOT ALREADY DONE) In the Settings > Developer settings > Personal access tokens > Fine-grained tokens page on GitHub, press the Generate new token button at the top-right corner to generate a new fine-grained personal access token.

2. (IF NOT ALREADY DONE) Fill-in the following fields in the New fine-grained personal access token page:

   • Token name: A sensible name to identify the newly created personal access token, e.g. For GitLab to GitHub project mirroring.
   • Resource owner: The namespace where you want to mirror the project from.
   • Expiration: Should be set as long as allowed by GitHub, which is currently 366 days.
   • Description: A sensible descriptive text of the newly created personal access token, you may leave this field empty if the Token name is sensible enough.
   • Repository access: All repositories.
   • Permissions:
     • Change Repository permissions > Contents to Read and write.
     • Change Repository permissions > Workflows to Read and write.

3. (IF NOT ALREADY DONE) Click the Generate token button at the bottom of the page to complete the personal access token generation.

4. (IF NOT ALREADY DONE) Copy the generated personal access token in the Fine-grained personal access tokens page(it will only be shown once) and save it somewhere secure and persistent(like in your preferred password manager application).

5. Create the GitHub mirror project.

6. Copy the clone URL of the GitHub Git repository.

7. In the Mirroring repositories section of the Settings > Repository page of the GitLab project, click the "Add new" button at the top right of the Mirrored repositories table.

8. Fill in the following fields of the Add new mirror repository form:

   • Git repository URL: Fill in the clone URL of the GitHub Git repository copied earlier.
   • Mirror direction: Push.
   • Authentication method: Username and Password.
   • Username: Fill in your GitHub username(the content shouldn't really matter as long as it's not a null string).
   • Password: Fill in the fine-grained personal access token you've generated previously.

9. Click the Mirror repository button at the bottom of the Mirroring repositories section to complete creating the Mirroring repository configuration.

10. Click the Update now at the right side of the mirroring repository configuration to trigger a manual push.

11. Verify whether the value of the Last successful update has changed to Just now.

    NOTE: If the value is still Never, try refreshing the page to fetch the latest status.

    If an Error label appears at the right side, check your settings and recreate a new repository mirroring configuration.

12. (OPTIONAL) Refresh the repository on GitHub to verify that the content does indeed synced from GitLab.

13. In the Features section of the Settings > General page of the GitHub mirror project, disable the following unneeded features:

    • Wikis
    • Issues
    • Projects

14. In the repository main page on GitHub, click the gear icon a the top right of the About panel to open the Edit repository details dialog, and set the following fields:

    • (OPTIONAL) Description: The project description text(should be the same as in the Settings > General page of the GitLab project).
    • Website: The project URL on GitLab.
    • (OPTIONAL) Topics: Sensible topic tags applied for the project(should be the same as in the Settings > General page of the GitLab project).
    • Include in the home page: Untoggle the following options unless you plan on using them:
      • Packages
      • Deployments

15. Click the Save changes at the down-left to apply the changes.

References

The following materials are referenced during the development of this project:

• Inline Scripts | Shell Scripts - Provisioning | Vagrant | HashiCorp Developer
  Explains how to run an inline script in a Vagrantfile.

Licensing

Unless otherwise noted(comment headers/REUSE.toml), this product is licensed under the 4.0 International version of the Creative Commons Attribution-ShareAlike license, or any of its more recent versions of your preference.

As an exception of the previous clause, this product can be licensed otherwise under the 2.0 version of the Apache license if it is used to instantiate/refactor a project based on it rather than using it in the making of another template project. This allows relicensing the project assets to your liking in your non-template projects with only a conformance requirement of attributing this product somewhere in your project/product credits/acknowledgment/copyright notice documentation/user interface.

This work complies to the REUSE Specification, refer to the REUSE - Make licensing easy for everyone website for info regarding the licensing of this product.