From 43148ea2d083806924f15f55680f4ae4562f5ace Mon Sep 17 00:00:00 2001 From: Thorsten Bruhns Date: Sat, 26 Nov 2022 12:54:42 +0100 Subject: [PATCH] documentation: some fixes --- changelogs/fragments/299-doc.yml | 5 ++ doc/development.adoc | 121 ++++++++++++++++++++++++++++++- doc/guides/advanced.puml | 8 +- doc/guides/beginner.adoc | 2 +- 4 files changed, 127 insertions(+), 9 deletions(-) diff --git a/changelogs/fragments/299-doc.yml b/changelogs/fragments/299-doc.yml index 1723b355d..c7c1dc94e 100644 --- a/changelogs/fragments/299-doc.yml +++ b/changelogs/fragments/299-doc.yml @@ -1,3 +1,8 @@ --- minor_changes: - "Documentation: Added feauturelist and missing picture (#299)" + +trivial: + - "beginner.adoc: typo" + - "developer.adoc: more details" + - "advanced.puml: small fix" diff --git a/doc/development.adoc b/doc/development.adoc index d6f733586..b7bfcde15 100644 --- a/doc/development.adoc +++ b/doc/development.adoc @@ -4,10 +4,69 @@ toc::[] :sectnums: :sectnumlevels: 4 -= Pull-Requests +== How to develop in `ansible-oracle`? +IMPORTANT: This is an example how most of the development in `ansible-oracle` is done. + +A Pull-Request is only accepted, when `github-Actions` are valid. -== Important Information +=== Prepare a development environment + +IMPORTANT: This chapter shows, how the development envionment could look like. + +You need an Ansible-Controller with an Editor or IDE of your own choice. + + + +=== Create Fork on github and contribute to the project + +link:https://docs.github.com/en/get-started/quickstart/contributing-to-projects[github] has a great documentation with details about creating a fork and branch to contribute to `ansible-oracle`. + +IMPORTANT: The `github-Actions` will automatically start, when the branchname starts with `pr` or in each Pull-Request. + +Please use a branch with 'pr'--prefix, when `ansible-lint` should be checked for each commit. + +=== pre-commit + +IMPORTANT: link:https://pre-commit.com/[pre-commit] is a nice tool for git. + +Each commit is locally checked against multiple rules, to prevent failures in github-Actions after pushing commits to github. + +This tool is recommended but not mandatory for contributing to `ansible-oracle`. + +.Installation (cd into repository before) +---- +pip install --user pre-commit +pre-commit install +---- + +.run outside git +---- +pre-commit run +---- + +=== Start Ansible-Container + +=== Start Playbook + +IMPORTANT: Don't forget to set the working branch in `requirements.yml`. + +Remove/Disable `devsec.hardening` for faster installation of Ansible collection, when devsec should not be tested. + + +.Edit requirements.yml +---- +--- +collections: + # - name: devsec.hardening + # version: 8.2.0 + - name: https://github.com/Rendanic/ansible-oracle.git + type: git + version: devbranch +---- + +.Execute ansible-playbook +---- +ansible-galaxy collection install --force -r requirements.yml && ansible-playbook -i inventory/hasfd -e hostgroup='all' playbooks/single-instance-asm.yml --limit '*19c*' +---- + +== Pull-Requests + +=== Important Information The ansible-oracle project introduced `antsibull-changelog` for managing the `CHANGELOG.rst` based on fragments in `changelogs/gragments`. @@ -17,13 +76,67 @@ If multiple PRs are open, the upper rule makes sure that no duplicate files are IMPORTANT: Each Pull-Requests needs a fragment from Release 3.0.0 onwards! -== Working with antsibull-changelog +<<<<<<< HEAD +== Create new Releases in `ansible-oracle` + +IMPORTANT: This is only needed for creating new Releases in `ansible-oracle` - not for development! + + +======= +== Create new Releases in `ansible-oracle` + +IMPORTANT: This is only needed for creating new Releases in `ansible-oracle` - not for development! + +>>>>>>> 2226b8a9fe5dec919cdb916059f233c63b914fc9 +=== Install antsibull-changelog + +---- +cd ansible-oracle/docker +docker-compose run --rm -w /git/ansible-oracle/example/beginner/ansible ansible bash + +pip3 install antsibull-changelog +---- + +=== Working with antsibull-changelog Changelogs for Collections: https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#releasing-a-new-version-of-a-collection -== Creating new releases +=== Creating new releases `antsibull-changelog release` reads `galaxy.yml` to get the release version automatically. The execution is aborted, when a release with the version is existing in `CHANGELOG.rst`. NOTE: The whole release process should be donw with a dedicated Pull-Request. + +---- +antsibull-changelog release +---- + +== Update Vagrantbox on vagrantcloud for examples + +IMPORTANT: This is only an example how to do it, when custom images should be used. + +=== Create new Box + +---- +git clone https://github.com/Rendanic/bento.git +cd bento +git checkout oc +cd packer_templates/oraclelinux/ +./oc_oracle-7.x_vbox.sh oracle-7.9-x86_64.json +---- + +=== Upload new Version + +IMPORTANT: Change the boxname to an account with write priviledges. + +.Upload new version after build: +---- +boxname="Rendanic/oraclelinux-7.x" +vagrantversion=$(date +%y%m%d) + +vagrant cloud version create ${boxname} "$vagrantversion" +vagrant cloud provider create ${boxname} virtualbox "$vagrantversion" +vagrant cloud provider upload ${boxname} virtualbox "$vagrantversion" ../../builds/oracle-7.9.virtualbox.box +vagrant cloud publish --release ${boxname} "$vagrantversion" virtualbox +---- diff --git a/doc/guides/advanced.puml b/doc/guides/advanced.puml index f5eae7fa3..0bb9bfee5 100644 --- a/doc/guides/advanced.puml +++ b/doc/guides/advanced.puml @@ -19,10 +19,6 @@ System_Boundary(host, "Host System", "PC/Notebook") { Container(ssh, "ssh", "ssh vagrant@192.168.56.161", $tags="software") Container(vagrant, "Vagrant", "", $tags="software") Container(git, "git", "git clone for Vagrantfile from ansible-oracle", $tags="software") - - SetPropertyHeader("Windows Environment Variable","Description") - AddProperty("VAGRANT_ANSIBLE_ORACLE_SW", "Drive with directory on Host System") - Container(instmediahost, "Installation Media", "Environment Variable for vboxsf mount in VM", $tags="media") } } Boundary(virtualbox, "VirtualBox") { @@ -40,7 +36,11 @@ System_Boundary(host, "Host System", "PC/Notebook") { Container(instmedia, "Installation Media from Environment Variable VAGRANT_ANSIBLE_ORACLE_SW mounted on /sw/oracle inside VM", "ORA 19c", $tags="media") } } + SetPropertyHeader("Windows Environment Variable","Description") + AddProperty("VAGRANT_ANSIBLE_ORACLE_SW", "Drive with directory on Host System") + Container(instmediahost, "Installation Media", "Environment Variable for vboxsf mount in VM", $tags="media") } +Rel_Up(instmediahost, instmedia, "vboxsf") Rel_Down(admin, tools, "") Rel_Down(conemu, vmansible, "ssh with agent forwarding") Rel_Down(vmansible, dbfs, "ssh with key from Agent") diff --git a/doc/guides/beginner.adoc b/doc/guides/beginner.adoc index 9d437d711..e784c95cf 100644 --- a/doc/guides/beginner.adoc +++ b/doc/guides/beginner.adoc @@ -182,7 +182,7 @@ ansible-playbook -i inventory/ -e hostgroup=dbfs playbooks/single-instance-fs.ym ---- The Database creation has been completed. + -See the follwoing chapter for details about how to work with the VM. +See the following chapter for details about how to work with the VM. === How to work with installed database