diff --git a/docs/img/repo_settings_abapgit_xml.png b/docs/img/repo_settings_abapgit_xml.png new file mode 100644 index 000000000..861e88574 Binary files /dev/null and b/docs/img/repo_settings_abapgit_xml.png differ diff --git a/docs/img/repo_settings_click.png b/docs/img/repo_settings_click.png deleted file mode 100644 index c40cec5f8..000000000 Binary files a/docs/img/repo_settings_click.png and /dev/null differ diff --git a/docs/img/repo_settings_locals.png b/docs/img/repo_settings_locals.png new file mode 100644 index 000000000..1633bce94 Binary files /dev/null and b/docs/img/repo_settings_locals.png differ diff --git a/docs/img/repo_settings_menu.png b/docs/img/repo_settings_menu.png new file mode 100644 index 000000000..a3e9baa5b Binary files /dev/null and b/docs/img/repo_settings_menu.png differ diff --git a/docs/img/repo_settings_write.png b/docs/img/repo_settings_write.png deleted file mode 100644 index 0eee792e4..000000000 Binary files a/docs/img/repo_settings_write.png and /dev/null differ diff --git a/docs/ref-dot-abapgit.md b/docs/ref-dot-abapgit.md index ee8547c5a..892d5f040 100644 --- a/docs/ref-dot-abapgit.md +++ b/docs/ref-dot-abapgit.md @@ -1,12 +1,15 @@ --- -title: .abapgit.xml +title: Repo Settings (.abapgit.xml) category: reference order: 10 --- **.abapgit.xml** is a special abapGit file. It contains meta information of the abapGit project. -.abapgit.xml can be edit via "Repo menu > Advanced > Repo settings" or via "abapGit menu > Advanced > Database util". +It is recommended to edit .abapgit.xml via "Repo menu > Advanced > Repo settings". +(In exceptional cases, you could edit the xml directly via "abapGit menu > Advanced > Database util".) + +![](img/repo_settings_menu.png) Example: abapGit's own .abapgit.xml @@ -25,13 +28,21 @@ Example: abapGit's own .abapgit.xml /README.md /package.json /changelog.txt + /.gitignore + /CODE_OF_CONDUCT.md + /abaplint.json + /.eslintrc.yaml ``` -# Description +# Repository Settings + +The following settings are stored in the repository and therefore valid for all users. + +![](img/repo_settings_abapgit_xml.png) ## Location The `.abapgit.xml` file must be located in the root folder of the git repository. @@ -46,7 +57,7 @@ The Git repository folder that defines the root folder where deserialization sta ## Folder Logic -abapGit follows two folder logics: PREFIX and FULL +abapGit follows two folder logics: PREFIX and FULL. ### PREFIX @@ -57,55 +68,72 @@ Valid prefix: * **ZFOO**_BAR * **ZFOO_BAR**_QUX -will give folder structure /bar/qux/ +will produce folder structure /bar/qux/ Invalid prefix: * ZFOO * ZBAR -The folder logic PREFIX allows to install the repository into a different parent package. This can even be local packages(`$*`), in that case no transport order is required. +The folder logic PREFIX allows to install a repository into a different parent package (in different systems). This can even be local packages (`$*`), in which case no transport order is required. ### FULL -Any package name is accepted +Any package name is accepted. * ZSOMETHING * ZHELLO -will give folder structure /zsomething/zhello/ +will produce folder structure /zsomething/zhello/ -The folder logic FULL forces the installation of the repository into packages with exactly the same name. This can be problematic for contributors who use a system where specific prefixes for the package names are to be used. +The folder logic FULL forces the installation of a repository into packages with exactly the same name. Note that this can be problematic for contributors who use a system where specific prefixes for the package names are to be used. -## Ignore +## Ignore files -Files which abapGit will not download into your ABAP system. +Files which abapGit will not download to your ABAP system. Typically, this includes references to readme, changelog, and license +files as well as repository configuration related to workflows like build or linting jobs. ## Requirements -ToDo +In this section, you can specify the minimum requirements that should be fulfilled to allow installation of the repository. Listed software components should exist in the target system and be at the given release or higher. If the target system matches the minimum release, then it must also be at the given patch level or higher. -## Local Settings +# Local Settings -### Write protected +The following settings are stored in and valid for the current system only. -Write protected is described here: [Write protected](http://docs.abapgit.org/ref-write-protect.html) +![](img/repo_settings_locals.png) -### Ignore subpackages +## Display name -Subpackages would be ignored through this option. +This setting overwrites the default name of the repository (which is derived from the later part of the repository URL). -### Only local objects +## Write protected -ToDo +If you write protect a repository, it will make sure that users cannot overwrite objects in the SAP system with objects from the repository. It helps enforcing that data can only go from the SAP system to the repository. -### Code inspector +Turning on this option disables pulls, uninstall of all objects, switching branches, etc. -The repository objects can be checked with the Code inspector or the ABAP Test Cockpit (ATC) before staging. It's possible to perform a code inspector or ABAP Test Cockpit check without maintaing a check variant. In this case the end user is prompted with a F4 search help to choose a check variant during runtime. +Caution: The option influences only processes within abapGit. It does **not** protect against changes to objects using other means like ABAP Workbench or ABAP Development Tools. -#### Code inspector check variant +## Ignore subpackages -By entering a Code inspector or ABAP Test Cockpit (ATC) check variant, the check is activated. Only global check variants are supported. Thus the check variant has to be available to all developers. A check variant can either make use of local checks of the developer system or a reference to a check variant on a remote ABAP Test Cockpit system. The available checks in a check variant on a remote ATC system may differ from the available checks of a check variant of the developer system due to the ATC system being on a newer release. For more details about release-specific availability of ABAP Test Cockpit security-related checks delivered by SAP Code Vulnerability Analyzer (CVA) see SAP Note `1921820`. +This setting impacts how abapGit determines which objects belong to a repository. The default is to select all objects assigned to the root SAP package including any other subpackages (and subpackages of subpackages). If "ignore subpackages" is turned on, then only objects of the root package are selected. -#### Block commit commit/push if code inspection has erros +## Only local objects -This option can be used to prevent staging if errors of priority 1 and 2 were found during the Code Inspector or ABAP Test Cockpit (ATC) check. Findings of priority ≥ 3 are not reported. A check variant must be configured to activate this option. abapGit won't change its behavior based on the transport settings of the `Transport Tool Integration` of the ATC setup in transaction `ATC`. If this option is not active and errors were found, the end user can stage anyway. It's not possible to view or request exemptions from within abapGit during the staging process. Furthermore it's not able to access the ATC check documentation for a finding from within abapGit. +This setting impacts how abapGit determines which objects belong to a repository. If "only local objects" is turned on, then the selection is limited to objects assigned to the current system (tadir-srcsystem = sy-sysid). + +## Code inspector + +The repository objects can be checked with the [Code inspector](https://help.sap.com/viewer/ba879a6e2ea04d9bb94c7ccd7cdac446/7.5.18/en-US/49205531d0fc14cfe10000000a42189b.html) or [ABAP Test Cockpit (ATC)](https://help.sap.com/viewer/ba879a6e2ea04d9bb94c7ccd7cdac446/7.5.18/en-US/62c41ad841554516bb06fb3620540e47.html) before staging. It's possible to perform a code inspector or ABAP Test Cockpit check without maintaing a check variant. In this case the end user is prompted with a F4 search help to choose a check variant during runtime. + +### Code inspector check variant + +By entering a Code inspector or the ABAP Test Cockpit check variant, the check is activated. Only global check variants are supported. Thus the check variant has to be available to all developers. A check variant can either make use of local checks of the developer system or a reference to a check variant on a remote ABAP Test Cockpit system. The available checks in a check variant on a remote ATC system may differ from the available checks of a check variant of the developer system due to the ATC system being on a newer release. For more details about release-specific availability of ABAP Test Cockpit security-related checks delivered by SAP Code Vulnerability Analyzer (CVA) see SAP Note [1921820](https://launchpad.support.sap.com/#/notes/1921820). + +### Block commit/push if code inspection has erros + +This option can be used to prevent staging if errors of priority 1 and 2 were found during the Code Inspector or ABAP Test Cockpit check. Findings of priority ≥ 3 are not reported. A check variant must be configured to activate this option. abapGit won't change its behavior based on the transport settings of the `Transport Tool Integration` of the ATC setup in transaction `ATC`. If this option is not active and errors were found, the end user can stage anyway. It's not possible to view or request exemptions from within abapGit during the staging process. Furthermore it's not able to access the ATC check documentation for a finding from within abapGit. + +## Serialize master language only + +By default, abapGit will serialize objects in all installed languages. If this option is turned on, then this process is limited to the master language defined in the repository settings (see above). diff --git a/docs/ref-icons.md b/docs/ref-icons.md new file mode 100644 index 000000000..78d74489a --- /dev/null +++ b/docs/ref-icons.md @@ -0,0 +1,39 @@ +--- +title: Icon Legend +category: reference +order: 25 +--- + +The following list provides a quick reference to icons used in abapGit. + +See also [abapGit Icon Font](https://github.com/abapGit/icon-font). + +Icon | Description | Code +:----- | :------------ | :------------ + | Arrow Down | (chevron-down) + | Arrow Left | (chevron-left) + | Arrow Right | (chevron-right) + | Arrow Up | (chevron-up) + | Favorite | (star) + | File - Binary | (file-image) + | File - Code | (file-code) + | File - General | (file) + | File - Object | (file-alt) + | Folder | (folder) + | Message - Error | (exclamation-circle) + | Message - Warning | (exclamation-triangle) + | News/Changelog | (arrow-circle-up) + | Object - Inactive | (bolt) + | Object - Locked | (lock) + | OK | (check) + | Repository - Branch | (code-branch) + | Repository - Merge | (code-commit) + | Repository - Offline | (plug) + | Repository - Online | (cloud-upload-alt) + | Repository Picker | (bars) + | SAP Package | (box) + | SAP Transport | (briefcase) + | Settings | (cog) + | (currently not used) | (fire-alt) + | (currently not used) | (sliders-h) + | (currently not used) | (snowflake) diff --git a/docs/ref-write-protect.md b/docs/ref-write-protect.md deleted file mode 100644 index 5d17c1e83..000000000 --- a/docs/ref-write-protect.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Write protect -category: reference -order: 30 ---- - -The write protected repository feature will make sure users cannot overwrite objects in the SAP system with objects from the git repository. So it helps enforcing that data can only go from the SAP system to the Git repository. - -The feature disables pulls, uninstall of all objects, switching branches etc. - -To enable: - -In the repo, click "Repo settings" - -![](img/repo_settings_click.png) - -Tick "Write protect" - -![](img/repo_settings_write.png) - -Click "Save" \ No newline at end of file