README.md

DSAG's UI5 best practice guide

this is not the guide itself (it's over at https://1dsag.github.io/UI5-Best-Practice/), but the corresponding repository with instructions on how to contribute to the guide.

Because the DSAG UI5 best practice guide is a living document 👨‍💻 - thriving on and with its' community 🥳

The document is written in (kramdown flavored) markdown and served via jekyll in github pages (https://1dsag.github.io/UI5-Best-Practice/).

Table of contents

• Table of contents
• Local Setup / Gettings started
  • Recommended: Development Container
    • Getting Started
  • Alternative: Local installation
    • Prerequisites for Windows
    • Installation Steps
• Developing
  • How to git commit messages
• Contributing
  • How to use Pull Requests in GitHub
  • linting of markdown content
• Licensing

Local Setup / Gettings started

Recommended: Development Container

This is the easiest way to have your development environment ready in no time. You get a ready to use configured Debian Container which is transparently used by Visual Studio Code.

Getting Started

Install the following programs:

• Visual Studio Code
• Remote Containers Extension
• Docker

Clone the repository with the command Remote-Containers: Clone Repository in Container Volume...

This will

• Clone the Repository in a Container Volume
• Build the Docker Image
• Start the Docker Container and map the required ports
• Mount the created Container Volume
• Install the required npm packages
• Install the required ruby gems

The only thing left to do is open the console in Visual Studio Code (it is attached to the running Development Container), navigate into the docs folder and start the Development Server:

cd docs
bundle exec jekyll serve --livereload

Alternative: Local installation

Prerequisites for Windows

• Install https://chocolatey.org/
• Install MSYS2 choco install msys2 https://chocolatey.org/packages/msys2
• Install Ruby choco install ruby https://chocolatey.org/packages/ruby
• Update Build Toolchain ridk install 3
• see setup local github pages site 😉

Installation Steps

• make sure, ruby 2.7 is installed on your system

• clone the repo

• switch to the document base $> cd docs

• $> bundle install
  for installing the github-pages jekyll incarnation

• start the local gh-pages instance, including automatic browser live-reload

  bundle exec jekyll serve --livereload
  Configuration file: /Users/you/UI5-Best-Practice/docs/_config.yml
              Source: /Users/you/UI5-Best-Practice/docs
         Destination: /Users/you/UI5-Best-Practice/docs/_site
   Incremental build: disabled. Enable with --incremental
        Generating...
         Jekyll Feed: Generating feed for posts
                      done in 0.233 seconds.
   Auto-regeneration: enabled for '/Users/you/UI5-Best-Practice/docs'
   LiveReload address: http://127.0.0.1:35729
      Server address: http://127.0.0.1:4000/
    Server running... press ctrl-c to stop.

• point your web browser to http://localhost:4000

Developing

How to git commit messages

commit messages are linted in order to allow for automatic later processing into CHANGELOG et al documents.
The linting occurs against the standards defined in the "conventional commit" guidelines, based on the Angular project ones.

The structure of a "conventional commit" message looks like:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

<type> can be any of

• build
• ci
• chore
• docs
• feat
• fix
• perf
• refactor
• revert
• style
• test

So a minimal commit message could look like...

feat: added basic testing chapter

…while a maxed out one might look like:

fix: correct minor typos in code

see the issue for details on typos fixed.
additionally, replaced the dreaded ortho-""
with straight/standard ones.

Reviewed-by: Z
Closes #133

Please refer to the conventional commits website for more details on all the possibilities of formatting a git commit message.

Contributing

How to use Pull Requests in GitHub

0. fork the repo
   

1. clone your fork into your local development environment
   

2. create a new local git branch
   

3. write, edit, code (most likely markdown content in /docs/**/*.
   👨‍💻
   repeat.

   note: we're using github flavoured markdown (gfm) that allows for extended markdown formatting

   git commit early, git commit often
   → watch out for the commit linting (see git commit messages)
   → enjoy the convenience of auto-markdown-linting (see linting of markdown content)

4. if applicable, clean up your git commit history

5. push the local branch to your fork

6. submit a pull request (PR)
   

7. write the PR message similar to the git commit messages, so squash-merging gets easy for the maintainers
   if applicable, referenc open issues in your commit message (https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)

8. add a reviewer to the PR
   

9. Changes necessary after the PR was created?
   Simply commit to the branch of your fork
   → the PR gets updated automatically
   → move the PR into draft mode until ready (then move to ready for review)

10. PR review process successfully completed?
    Then the PR will be merged by any of the maintainers and it’s time for 🎉

linting of markdown content

Any markdown content (in /docs/**/*) is linted via markdownlint both for quality assurance and convenience.
For quality assurance, to have the markdown-files max standard compliant, so subsequent processing and exporting is possible without running into formatting issues.
For convenience, because small markdown formatting mistakes are automatically fixed via the markdownlint upon commit - the markdownlint cli injects those fixes prior to the git commit, so don’t be surprised 😉

Licensing

This project uses the CC BY 4.0 license : LICENSE