From 8121aa829e4f227c072b6b03563bce1f6b96d5ea Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 16 Apr 2024 15:39:07 +0100 Subject: [PATCH 1/9] writing blog posts for Galasa --- .../docs/blogs/galasa-blogging.md | 200 ++++++++++++++++++ .../docs/ecosystem/ecosystem-architecture.md | 3 + .../docs/ecosystem/test-streams.svg | 88 ++++++++ 3 files changed, 291 insertions(+) create mode 100644 src/markdown-pages/docs/blogs/galasa-blogging.md create mode 100644 src/markdown-pages/docs/ecosystem/test-streams.svg diff --git a/src/markdown-pages/docs/blogs/galasa-blogging.md b/src/markdown-pages/docs/blogs/galasa-blogging.md new file mode 100644 index 00000000..cf5ae83b --- /dev/null +++ b/src/markdown-pages/docs/blogs/galasa-blogging.md @@ -0,0 +1,200 @@ +--- +path: "/hub/blog/category/galasa-blogging" +title: "Blogging about Galasa" +--- + +Galasa-related blogs are hosted on the Open Mainframe Project (OMP) website. Use the following information to find out how to check the status of blog posts, how to write a Galasa blog post, and best practices for writing blogs. + +[Tracking blog status](#tracking)
+[Blog preparation](#preparing)
+[Pre-publishing steps](#publishing)
+[Review Process](#reviewing)
+[Content Guidelines](#guidelines)
+[Promotion](#promoting)
+[Best practices](#bestpractice)
+ + + +## Tracking blog status + +The pipeline of blogs for Galasa is available for viewing on a publicly accessible GitHub board. You can access the board to view what future articles are in plan, and to track the status of any blogs that are in progress. You can assign yourself to a blog issue if you want to, or create a new issue for a blog that you want to write. + +## Preparing your blog post + + - Go to the `Media Backlog` column in the GitHub board to see what other blogs are being worked on in case there is a blog already being authored/prepared on the same topic. + - If no similar issue exists, create one and assign it to yourself along with a description of the blog article that you want to write. Use existing issues as templates. As a minimum the issue must include a Story, Background, and Tasks section. + + +## Writing your blog + +You can write your blog as a Word document and attach it to your issue. Remember to read the information provided about [best practices](#bestpractice) for writing your blogs. + +Include the following sentences as a call to action at the end of your blog, shown below as it should appear. +"To find out more about Galasa visit the [Galasa website](https://galasa.dev), or join the community in our [Galasa Slack](https://openmainframeproject.slack.com/archives/C05TCCQDE65) workspace. [Register to join](https://openmainframeproject.slack.com/signup#/domain-signup) first if you're not yet a member." + +You can also link to relevant topics in the Galasa website that support the content of your blog post. + + +### Checking your blog + +After writing your blog, remember to check that you have + - compelling title and opening paragraph (discoverability is critical!) + - featured image and visuals in place + - appropriate links and tags, including a call to action + + +### Pre-publishing steps + + - Attach your blog article in Word format to the relevant blog issue. + - Assign `galasa-team` as a reviewer to your issue. + - Move your issue into the `Review` column of the GitHub board. + + +## Review process + + - One or more members of the Galasa team will review the blog post + - The reviewers will work with the author for any updates or changes required + - OMP team will do final check for grammar and branding + - OMP will schedule it and promote via social media + - OMP team will let author know publication date and share via social media + - To check on the status of your blog check the GitHub board. This lets you see the reviewers of your blog as well as enable you to read and add any Github comments about its publication. See the [Tracking blog status](#tracking) section for more information. . + + + ## Content guidelines + + As a blog writer you can write about any topic that you're interested in and that will provide value to the Galasa community. The content on our blog consists of: + + - Articles about Galasa features and functions + - Technical content and how-to's + - Stories about Galasa deployments + - Use cases and success stories + - Reports from Galasa events + + Other topics are welcome, but it needs to have a direct link to the Galasa community + + +## Promotion + +Your blog will be shared on the Open Mainframe Project's [X](https://twitter.com/OpenMFProject) and [linkedIn](https://www.linkedin.com/company/the-open-mainframe-project/) channels. + + +## Best practices + +When writing your blog, review the top tips in the following sections to make sure that you are following best practices. + +### About the title + +A strong title clearly conveys the value that someone going to get out of the post and exactly what topics/concepts/ideas are covered. Review the following key points on best practices for writing good titles: + +- Avoid vague titles as these discourage people from clicking.  + +- Be concise - never use three words when one will do. + +- Establish the topic/keyword on which the post focuses. Keyword(s) should be at the front of the title. Keyword stuffing is not good, but one or two keywords works well so long as the title makes sense. + +- Create a working title - Google only displays the first 50-60 characters of the title, and cuts the rest. You can have a title that’s longer than 60 characters, but fit the important information before the cut-off point. + +- Use no more than 8 words ideally. (15 max) + +After you finish the post, go back to the title to check that it accurately reflects the content of the post. You can include `Galasa` in the title if it makes sense to do so. + +### About the short description + +A brief summary of the blog, including primary keyword(s). + +- Watch the length -  Google keeps the first 150-160 characters (including spaces) of your short description, and cuts the rest. Ensure that the important aspects are included early on to maximize searcher interest.​ + +- Write good copy -  The better the description, the more likely someone will click through to the blog post. + + +### About headers + +Heading tags are used to structure your pages for both the reader and search engines. + +From the perspective of the reader, subheaders to break up the text into logical sections, and quickly and clearly tell them what each section is about. + +From the perspective of the search engine, header tags help search crawler bots understand what the page is about, and improve SEO. + +Header 1 tags: + +An H1 heading stands apart from other headings because it’s treated by search engines as the title of the page.  + +Include the primary keyword in Header 1 (H1) and don’t use more than one H1.  + +  +Header 2 and 3 tags: + +Internal headers help to break up content and improve the reading experience for users. Like the title, the subheaders should clearly tell the reader the value they will get from reading the section. Avoid generic subheaders like "Introduction," "Conclusion," or "Next steps." + +Review the following key points on best practices for writing good subheadings: + +- Use a subheader to introduce each unique subtopic/task/idea/concept in a post. You should be able to skim only the title and subheaders and have an idea of what the post is about. + +- Keep the subheader concise and descriptive. + +- Include keywords and other important words at the beginning of the subheader. + +- Use sentence case (capitalize only the first word and proper nouns). + +- Maintain shallow structure - don't go below H3. Anything more gets confusing.​ + +- Form query-like headings - Treat each heading as an additional opportunity to rank in search. To this end, each heading should sound either like a query or an answer to a query - keywords included. + + +- Be consistent with all headings - all headings should be written in such a way that if you were to remove all the text and keep only the headings, they would read like a list. + +### About images:  + +Including images in your blog is an excellent way to break up text, catch your reader’s eye, and back up points you make in the article. Include an alt text for your image. The text helps visually impaired readers and allows search engines to index your image properly. The alt text should describe the image – only use focus keywords if appropriate. + +### About links: + +It is important to provide links that will help readers understand the concepts in the post, provide further information, and give them the opportunity to move from the blog page to, for example, a galasa.dev page. + +Link anchor text should be descriptive. Don't link the word "here" when you can name or describe the resource you are linking to. For example, + +Yes: Learn more about Galasa by reading the [Getting started](https://galasa.dev/docs) documentation. + +No: Learn more about Galasa [here](https://galasa.dev/docs). + +### Call to action links (CTAs): + +Every blog post you write should include at least one CTA. CTAs are the ultimate action that you want someone to take after reading the post , providing a clear next step to follow. Make sure to include descriptive text on the link. + +CTAs may include the following: + +- Link to a page on galasa.dev + +- Link to another blog post/web page for more info or as part of a series of blog posts + +- Link to documentation, samples, code etc  for example in GitHub + +- Link to a public Slack channel, or somewhere to raise issues eg project management repo in GitHub + +### About keywords: + +Determine which Google search keywords are best suited for your content and target audience (i.e., what are you communicating and to whom? What keywords are they likely to use?). Include these keywords in your title and related words in the body, especially the first paragraph. A long-tail focus keyword that is used naturally throughout your blog and describes your content will maximise SEO. + + - Be sure your title, opening paragraph (and featured image) will stand out in a search by your target audience (i.e., will it get people to click your entry over all the other Google results?) + +- Use focus keywords 2-3 times in the post, including once in the first paragraph. + +- Avoid "keyword stuffing". Don't put in too many keywords or force keywords in where they do not make sense. + +### Post length:  + +Research suggests the ideal blog post length is between 1,500 - 2,500 words, but this depends on the type of post as different topics require different depths of content. For example, some “how to” posts will need to be longer that some more “conceptual” ones.  + +  +Posts that are too short (less than 800 words) won’t rank highly.  + +- 1,300 - 1,700 words: Typical length for “What is ...” blog posts + +- 1,700 - 2,100 words: Typical length for “How to ...” posts. + +- 1,500 - 2,500 words: Ideal length for high ranking by search engines. + +- 4,000 words: extremely detailed, authoritative post + + + diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md index 325fabcb..4ca30c10 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md @@ -5,6 +5,9 @@ title: "Ecosystem Architecture" The following diagram provides a high-level representation of the Galasa Ecosystem architecture:

![Galasa ecosystem architecture:](ecosystem-overview-new.svg) + +The following diagram provides a high-level representation of test stream architecture:

![Galasa ecosystem architecture:](test-streams.svg) +
The Ecosystem is made up of a collection of microservices for orchestrating runtimes, monitoring tests and resources, and providing clean-up of those resources if required. The Ecosystem provides a centralized store for run configurations, a single location for storing all test results and test artifacts, and utilizes a REST endpoint that can be called from any IDE or pipeline. diff --git a/src/markdown-pages/docs/ecosystem/test-streams.svg b/src/markdown-pages/docs/ecosystem/test-streams.svg new file mode 100644 index 00000000..41a10798 --- /dev/null +++ b/src/markdown-pages/docs/ecosystem/test-streams.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From c73f88fee9eccf49fd1cec67eb9cb4a6df0d29eb Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 16 Apr 2024 15:48:07 +0100 Subject: [PATCH 2/9] remove paragraph and link --- src/markdown-pages/docs/ecosystem/ecosystem-architecture.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md index 4ca30c10..2e7c32f9 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md @@ -6,8 +6,6 @@ title: "Ecosystem Architecture" The following diagram provides a high-level representation of the Galasa Ecosystem architecture:

![Galasa ecosystem architecture:](ecosystem-overview-new.svg) -The following diagram provides a high-level representation of test stream architecture:

![Galasa ecosystem architecture:](test-streams.svg) -
The Ecosystem is made up of a collection of microservices for orchestrating runtimes, monitoring tests and resources, and providing clean-up of those resources if required. The Ecosystem provides a centralized store for run configurations, a single location for storing all test results and test artifacts, and utilizes a REST endpoint that can be called from any IDE or pipeline. From 5439f215d0666a47713ebd60e06dac2aa815eca0 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 16 Apr 2024 15:50:11 +0100 Subject: [PATCH 3/9] remove image --- .../docs/ecosystem/test-streams.svg | 88 ------------------- 1 file changed, 88 deletions(-) delete mode 100644 src/markdown-pages/docs/ecosystem/test-streams.svg diff --git a/src/markdown-pages/docs/ecosystem/test-streams.svg b/src/markdown-pages/docs/ecosystem/test-streams.svg deleted file mode 100644 index 41a10798..00000000 --- a/src/markdown-pages/docs/ecosystem/test-streams.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From a3e3914c79e1f7c16f62e056f578a28b3ab09315 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 17 Apr 2024 10:18:24 +0100 Subject: [PATCH 4/9] minor updates --- src/markdown-pages/docs/blogs/galasa-blogging.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/markdown-pages/docs/blogs/galasa-blogging.md b/src/markdown-pages/docs/blogs/galasa-blogging.md index cf5ae83b..f46142b6 100644 --- a/src/markdown-pages/docs/blogs/galasa-blogging.md +++ b/src/markdown-pages/docs/blogs/galasa-blogging.md @@ -54,7 +54,6 @@ After writing your blog, remember to check that you have - One or more members of the Galasa team will review the blog post - The reviewers will work with the author for any updates or changes required - - OMP team will do final check for grammar and branding - OMP will schedule it and promote via social media - OMP team will let author know publication date and share via social media - To check on the status of your blog check the GitHub board. This lets you see the reviewers of your blog as well as enable you to read and add any Github comments about its publication. See the [Tracking blog status](#tracking) section for more information. . @@ -186,11 +185,11 @@ Determine which Google search keywords are best suited for your content and targ Research suggests the ideal blog post length is between 1,500 - 2,500 words, but this depends on the type of post as different topics require different depths of content. For example, some “how to” posts will need to be longer that some more “conceptual” ones.    -Posts that are too short (less than 800 words) won’t rank highly.  +Posts that are too short (less than 500 words) won’t rank highly.  -- 1,300 - 1,700 words: Typical length for “What is ...” blog posts +- 800 - 1,700 words: Typical length for “What is ...” blog posts -- 1,700 - 2,100 words: Typical length for “How to ...” posts. +- 1,000 - 2,100 words: Typical length for “How to ...” posts. - 1,500 - 2,500 words: Ideal length for high ranking by search engines. From a5b2e7fe80fe77bfd63f538058fcc7832388cb02 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 8 May 2024 13:53:14 +0100 Subject: [PATCH 5/9] add authentication link to test mode topic --- .../writing-own-tests/running-test-modes.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index 77abc593..003a5b12 100644 --- a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md +++ b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md @@ -20,13 +20,18 @@ There are three modes in which you can run a Galasa test:

- remotely, by submitting the test to run in the Galasa Ecosystem
+If you are running a test locally but using a shared configuration that is hosted by the Galasa Ecosystem, or running a test remotely by submitting the test to run in the Galasa Ecosystem, you are interacting with the Galasa Ecosystem. + +Before you can interact with the Galasa Ecosystem, you must authenticate with it by using a personal access token. Tokens are stored in the `GALASA_TOKEN` in the `galasactl.properties` in your Galasa home folder. You can request a personal access token by using the Galasa Web UI. For more information about setting up authentication with an Ecosystem, see the [Configuring authentication](../ecosystem/ecosystem-authentication) documentation. + + The mode in which you choose to run a test depends on what you are trying to achieve. Use the following information to understand which mode is most appropriate for a given scenario. ## Running a test locally -When you run a test locally, without using shared configuration, everything runs on your local machine. The Galasa bootstrap file is blank and makes no reference to an ecosystem. The Galasa framework is launched within the JVM on the local machine and the local file system holds all the configuration that is used by the test. The test runs in the local JVM and all test results and artifacts are stored on the local disk. +When you run a test locally, without using shared configuration, everything runs on your local machine. The Galasa bootstrap file is blank and makes no reference to an Ecosystem. The Galasa framework is launched within the JVM on the local machine and the local file system holds all the configuration that is used by the test. The test runs in the local JVM and all test results and artifacts are stored on the local disk. ![running in local mode:](running-local.svg) @@ -35,21 +40,21 @@ You can run a test in this mode by using the `runs submit local` Running a test in the Galasa Ecosystem -To submit your test to an Ecosystem for remote execution, the Galasa bootstrap is set to the URL of the Galasa Ecosystem in which you want to run your test. The configuration of the test is also held within that ecosystem, and Galasa starts up in a container in which the test code will run. The test results and artifacts are stored in a database within the specified ecosystem, and users on client machines can view the test results. +To submit your test to an Ecosystem for remote execution, the Galasa bootstrap is set to the URL of the Galasa Ecosystem in which you want to run your test. The configuration of the test is also held within that Ecosystem, and Galasa starts up in a container in which the test code will run. The test results and artifacts are stored in a database within the specified Ecosystem, and users on client machines can view the test results. ![running remotely:](run-remote.svg) -You can run a test in this mode by setting up your bootstrap file to refer to the ecosystem that you want to use and running the `runs submit` Galasa CLI command. +You can run a test in this mode by setting up your bootstrap file to refer to the Ecosystem that you want to use and running the `runs submit` Galasa CLI command. ## Running a test locally but using shared configuration -When you run a test locally, but using shared configuration, the Galasa bootstrap is set to the URL of the Galasa Ecosystem where the shared configuration is stored. The Galasa framework is launched within the JVM on the local machine, but the framework consults the remote ecosystem to read configuration data, but not the credentials properties as these are drawn from a local file. This is the key difference between running a test in this "hybrid" mode versus running a test locally without using shared configuration. In hybrid mode, the test still runs in the local JVM and all test results and artifacts are stored on the local disk. +When you run a test locally, but using shared configuration, the Galasa bootstrap is set to the URL of the Galasa Ecosystem where the shared configuration is stored. The Galasa framework is launched within the JVM on the local machine, but the framework consults the remote Ecosystem to read configuration data, but not the credentials properties as these are drawn from a local file. This is the key difference between running a test in this "hybrid" mode versus running a test locally without using shared configuration. In hybrid mode, the test still runs in the local JVM and all test results and artifacts are stored on the local disk. ![running in local mode with shared configuration:](hybridrunmode.svg) -You can run a test in this mode by setting up your bootstrap to refer to the ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. +Once you have configured your authentication, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. ### When to run a test in the Galasa Ecosystem @@ -60,7 +65,7 @@ Running a test remotely is useful in the following scenarios: If you are able to dynamically provision a system, then running tests from a local JVM can work well, as the system under test might have few resource contraints and can be used exclusively by the tests before being de-provisioned. However, if you want to run many test in parallet, you cannot do so reliably from a single system using the local JVM method on one user account. Any contention to name test runs uniquely, or other stateful changes in the test framework might cause the tests to clash, over-write each other, fail, or produce unexpected results. Running multiple tests in series can avoid some of these issues but running large numbers of tests in this way can take a long time. -To reliably run many tests in parallel, deploy your tests to the Galasa Ecosystem, letting the ecosystem manage the test runs, and the Galasa Manager components manage any shared or constrained resources. +To reliably run many tests in parallel, deploy your tests to the Galasa Ecosystem, letting the Ecosystem manage the test runs, and the Galasa Manager components manage any shared or constrained resources. - Test results and reports need gathering from a single point. For example, when test results need reporting or exporting to another report-generating system, or when bug investigation can proceed by independent inspection test results and artifacts. From f70a0e6747b56916ccf7fdcd593290a83443054d Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 8 May 2024 13:57:01 +0100 Subject: [PATCH 6/9] add reminder for authentication --- .../docs/writing-own-tests/running-test-modes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index 003a5b12..2389415f 100644 --- a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md +++ b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md @@ -45,7 +45,7 @@ To submit your test to an Ecosystem for remote execution, the Galasa bootstrap i ![running remotely:](run-remote.svg) -You can run a test in this mode by setting up your bootstrap file to refer to the Ecosystem that you want to use and running the `runs submit` Galasa CLI command. +After configuring authentication, you can run a test in this mode by setting up your bootstrap file to refer to the Ecosystem that you want to use and running the `runs submit` Galasa CLI command. ## Running a test locally but using shared configuration @@ -54,7 +54,7 @@ When you run a test locally, but using shared configuration, the Galasa bootstra ![running in local mode with shared configuration:](hybridrunmode.svg) -Once you have configured your authentication, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. +After configuring authentication, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. ### When to run a test in the Galasa Ecosystem From 69e964769f85ab473185fe47af27c9060e8850c2 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 8 May 2024 14:23:48 +0100 Subject: [PATCH 7/9] add bootstrap prop for hybrid --- .../docs/writing-own-tests/running-test-modes.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index 2389415f..7eb288c6 100644 --- a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md +++ b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md @@ -54,6 +54,18 @@ When you run a test locally, but using shared configuration, the Galasa bootstra ![running in local mode with shared configuration:](hybridrunmode.svg) +To run tests in hybrid mode, add the following properties into your local `bootstrap.properties` file: + +``` +framework.config.store=galasacps://my.ecosystem.url/api +framework.extra.bundles=dev.galasa.cps.rest +``` + +where:
+- `galasacps://my.ecosystem.url/api` tells Galasa that `https://my.ecosystem.url/api` is the location of the Ecosystem REST API and
+- `framework.extra.bundles` indicates that the Galasa framework should load the `dev.galasa.cps.rest` extension. This extension tells the Galasa framework how to handle URLs that start with `galasacps` as the *scheme* part of the URL.
+ + After configuring authentication, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. ### When to run a test in the Galasa Ecosystem From 28060050f734803f085c4da5f3dee90bb511b109 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 8 May 2024 17:12:10 +0100 Subject: [PATCH 8/9] additional info from Mike --- .../docs/writing-own-tests/running-test-modes.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index 7eb288c6..f3f7970b 100644 --- a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md +++ b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md @@ -62,11 +62,10 @@ framework.extra.bundles=dev.galasa.cps.rest ``` where:
-- `galasacps://my.ecosystem.url/api` tells Galasa that `https://my.ecosystem.url/api` is the location of the Ecosystem REST API and
-- `framework.extra.bundles` indicates that the Galasa framework should load the `dev.galasa.cps.rest` extension. This extension tells the Galasa framework how to handle URLs that start with `galasacps` as the *scheme* part of the URL.
+- `https://my.ecosystem.url` refers to the Web UI used to allocate tokens and
+- `framework.extra.bundles` tells the Galasa framework to load the `dev.galasa.cps.rest` extension. This extension tells the Galasa framework how to handle URLs that start with `galasacps` as the *scheme* part of the URL.
- -After configuring authentication, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. +After setting the `GALASA_TOKEN` to be a valid token for the Ecosystem from which the CPS property values will be drawn, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `galasactl runs submit local` Galasa CLI command. ### When to run a test in the Galasa Ecosystem From 6a4a4907713efc40825b1da520d65baffd8ce011 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 14 May 2024 11:42:49 +0100 Subject: [PATCH 9/9] review comments plus core manager update --- src/markdown-pages/docs/managers/core-manager.md | 4 ++-- .../docs/writing-own-tests/running-test-modes.md | 7 +++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/src/markdown-pages/docs/managers/core-manager.md b/src/markdown-pages/docs/managers/core-manager.md index cf9fec11..f42bb8db 100644 --- a/src/markdown-pages/docs/managers/core-manager.md +++ b/src/markdown-pages/docs/managers/core-manager.md @@ -58,10 +58,10 @@ The following are properties used to configure the Core Manager: | Property: | Resource String Pattern CPS Property | | --------------------------------------- | :------------------------------------- | | Name: | core.resource.string.[length].pattern | -| Description: | Defines the pattern of characters within a string of a specified length. The patterns are from the Galasa ResourcePoolingService which uses a homegrown syntax. | +| Description: | The Resource String Pattern CPS property allows Galasa to form a string based upon a certain standard or pattern, for example, must begin with the letter `A`, must end with a numeral. The patterns are formed from the Galasa `ResourcePoolingService` which uses a custom syntax. This property is used when the Core Manager provisions a `@ResourceString` into a test. This string can used for anything within the test class, for example, to create new z/OS PDS names, or a piece of data that the test will use. The string must be unique to that test across all the other tests within the Ecosystem. | | Required: | No | | Default value: | {A-Z} for each byte for the specified length | -| Valid values: | For each character the value can be a constant or a random choice from a literal, eg {A-Z results in a single character between A and Z inclusive. {0-9} or {a-zA-Z0-9} are options. DFH{A-Z}{0-1}{0-9}{0-9}{0-9}, results in DFHA1789 for example, the 4th character can only be 0 or 1. +| Valid values: | For each character the value can be a constant or a random choice from a literal, eg {A-Z} results in a single character between A and Z inclusive. {0-9} or {a-zA-Z0-9} are options. DFH{A-Z}{0-1}{0-9}{0-9}{0-9}, results in DFHA1789 for example, the 5th character can only be 0 or 1. | Examples: | core.resource.string.8.length={A-Z}{A-Z}{A-Z}{A-Z}{A-Z}{A-Z}{A-Z}{A-Z}
 | diff --git a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index f3f7970b..43ac879c 100644 --- a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md +++ b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md @@ -49,7 +49,10 @@ After configuring authentication, you can run a test in this mode by setting up ## Running a test locally but using shared configuration -When you run a test locally, but using shared configuration, the Galasa bootstrap is set to the URL of the Galasa Ecosystem where the shared configuration is stored. The Galasa framework is launched within the JVM on the local machine, but the framework consults the remote Ecosystem to read configuration data, but not the credentials properties as these are drawn from a local file. This is the key difference between running a test in this "hybrid" mode versus running a test locally without using shared configuration. In hybrid mode, the test still runs in the local JVM and all test results and artifacts are stored on the local disk. +When you run a test locally, but using shared configuration, you need to run the `galasactl auth login` command to access the remote system using the Galasa bootstrap. You can then unset the bootstrap so that your local `bootstrap.properties` file is used, or alternatively you can refer explicitly to the local bootstrap file. For more information about the `galasactl auth login` command, see the [Configuring authentication](../ecosystem/ecosystem-authentication) documentation. + + +The Galasa framework is launched within the JVM on the local machine, but the framework consults the remote Ecosystem to read configuration data, but not the credentials properties as these are drawn from a local file. This is the key difference between running a test in this "hybrid" mode versus running a test locally without using shared configuration. In hybrid mode, the test still runs in the local JVM and all test results and artifacts are stored on the local disk. ![running in local mode with shared configuration:](hybridrunmode.svg) @@ -65,7 +68,7 @@ where:
- `https://my.ecosystem.url` refers to the Web UI used to allocate tokens and
- `framework.extra.bundles` tells the Galasa framework to load the `dev.galasa.cps.rest` extension. This extension tells the Galasa framework how to handle URLs that start with `galasacps` as the *scheme* part of the URL.
-After setting the `GALASA_TOKEN` to be a valid token for the Ecosystem from which the CPS property values will be drawn, you can run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `galasactl runs submit local` Galasa CLI command. +After setting the `GALASA_TOKEN` to be a valid token for the Ecosystem from which the CPS property values will be drawn, log into the Ecosystem by running the `galasactl auth login` command. You can then run a test in hybrid mode by setting your bootstrap to refer to the Ecosystem in which the shared configuration is stored, and using the `galasactl runs submit local` Galasa CLI command. ### When to run a test in the Galasa Ecosystem