docs: improve counter and list example comments #3818

yonbh · 2024-05-10T14:33:50Z

What type of PR is this?
/kind documentation

What this PR does / Why we need it:

Improve documentation regarding Counters and Lists on https://agones.dev/site/docs/reference/fleet/.
Fix typo on https://agones.dev/site/docs/guides/counters-and-lists/ .

Some of the changes include making it more consistent between the usage of rooms or players as examples in counters and lists whenever possible.

The added documentation on https://agones.dev/site/docs/reference/fleet/ roughly matches the one on https://agones.dev/site/docs/reference/gameserver/ for consistency.

Which issue(s) this PR fixes:

Special notes for your reviewer:

google-cla · 2024-05-10T14:33:54Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

agones-bot · 2024-05-10T15:16:11Z

Build Failed 😱

Build Id: 3d6f705a-0a9d-4ca4-b452-a09f064cd672

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-05-10T17:08:05Z

Build Succeeded 👏

Build Id: d93a7ef3-6dc8-41c2-b6de-eceaae8c0087

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://a5a351b-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3818/head:pr_3818 && git checkout pr_3818
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-a5a351b-amd64

markmandel · 2024-05-13T23:15:09Z

site/content/en/docs/Reference/fleet.md

@@ -58,11 +58,11 @@ spec:
  # Which gameservers in the Fleet are most important to keep around - impacts scale down logic.
  # priorities:
  # - type: Counter # Sort by a “Counter”
-  #   key: player # The name of the Counter. No impact if no GameServer found.
-  #   order: Descending # Default is "Ascending" so smaller capacity will be removed first on down scaling.
+  #   key: rooms # The name of the Counter. No impact if no GameServer found.


Ah good catch! Thank you! Got that in the examples.yaml, but not here.

https://github.com/googleforgames/agones/blob/main/examples/fleet.yaml has been updated with the move to beta -- but can we make the descriptions match across both (particularly the "available capacity" addition ?

Thanks for the feedback! Changed in 1716e09.

Added the Beta information and made the descriptions in fleet.yaml and fleet.md more consistent.

markmandel · 2024-05-13T23:23:28Z

site/content/en/docs/Reference/fleet.md

+      # counters: # counters are int64 counters stored against a GameServer in the fleet that can be incremented and decremented by set amounts. Keys must be declared at Fleet creation time.
+      #   games: # arbitrary key.
+      #     count: 0 # initial value.
+      #     capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details.


Suggested change

# capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details.

# capacity: 100

Thanks for adding the Counter and List example here - was missing!

Since this is the GameServer template, I think we can keep this pretty low on the description, since that's what the GameServer reference is for -- I'd bring this down to the level we have in https://github.com/googleforgames/agones/blob/release-1.40.0/examples/fleet.yaml

Some for the other fields.

Changed in 188f491 and made both files more consistent.

…ference files Also includes some tidying up of comments

…ple and reference file

agones-bot · 2024-05-14T12:01:52Z

Build Failed 😱

Build Id: a2eb7c5e-36bf-46e9-98d6-5704523689a5

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-05-14T12:07:31Z

Build Failed 😱

Build Id: 2b470684-ef36-4078-8993-e13dc45693b0

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-05-14T13:53:25Z

Build Succeeded 👏

Build Id: 75254938-bd73-450a-8ae8-5048d40ca623

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://c9bed05-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3818/head:pr_3818 && git checkout pr_3818
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-c9bed05-amd64

zmerlynn · 2024-05-16T18:34:01Z

cc @igooch for extra eyes

markmandel · 2024-05-16T23:10:23Z

site/content/en/docs/Reference/fleet.md

+      #     count:  # Count and/or capacity must be listed (but may be nil) otherwise the counter will by dropped by the CRD schema.
+      # lists:
+      #   players:
+      #     capacity:  # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema.


Suggested change

# capacity: # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema.

Matching the landing page.

I have now removed the verbose comments and made it match landing page with:

players: values: []

markmandel · 2024-05-16T23:10:51Z

site/content/en/docs/Reference/fleet.md

+      # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features.
+      # Now in Beta, and enabled by default
+      # counters:
+      #   players:


Suggested change

# players:

# rooms:

This has now been swapped

markmandel · 2024-05-16T23:15:25Z

examples/fleet.yaml

@@ -95,7 +100,7 @@ spec:
      # Now in Beta, and enabled by default
      counters:
        players:


Ow, I just realised my head hurts. I thought I'd fixed this everywhere when writing https://agones.dev/site/docs/guides/counters-and-lists/ , but clearly I missed some.

What we should have in all examples and docs:

rooms - is a counter
players is a list.

Somewhere this all got messed up, with an rooms being a list, and the introduction of sessions - but the above landing page, that should be the source of truth.

Sorry to make you go back and forth - I just noticed this.

Let's stick to players and rooms and remove all else please 😄

Hey no worries at all! Anything to make to make the docs better 🕺.

I have now removed mentions of sessions in and made rooms only used as an example as counters files e.g., fleet.yaml and gameserver.yaml in examples and fleet.md and gameserver.md in Reference.

However as a result of this examples for lists using rooms which showed initial values were also removed. If the intention of this was to show user's they are able to set initial values, I can revert this and change the wording from rooms to maybe map and initial values to be map1, map2, etc.

I'd prefer to leave in some mention of the above either in the example or the docs. The idea is to show that you can the same key in Counters as in List, that a List can have starting values, and that certain values may be nil.

Okie dokes. As that is the intention, I have reintroduced them in gameserver.yaml in examples and gameserver.md in References since GameServer would be the source of most user's reference when viewing the docs in addition to it being linked from the CountersAndLists documentation page itself.

Commits: 07e491d, 0362020

agones-bot · 2024-05-17T11:09:45Z

Build Failed 😱

Build Id: 6576db29-672a-484c-89f6-f1a2cd65a231

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

…er-list-example-comments

agones-bot · 2024-05-17T13:36:39Z

Build Failed 😱

Build Id: a55d43fe-0269-42d2-83b4-6886273e2b34

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-05-17T13:43:06Z

Build Failed 😱

Build Id: d0f97635-6084-4e0e-9e3a-18e8f20a701d

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

…unters and players a list

agones-bot · 2024-05-17T13:53:27Z

Build Failed 😱

Build Id: 3746ba0f-c110-4992-97fb-ee961771a419

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

…t and list landing page

agones-bot · 2024-05-17T14:04:22Z

Build Failed 😱

Build Id: 1bae152a-2b80-4d0e-a502-90c69342e3e4

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

…erver

agones-bot · 2024-05-17T14:11:59Z

Build Failed 😱

Build Id: 69a29ef8-cc01-4be1-ad9c-57776850d71f

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-05-17T14:25:56Z

Build Failed 😱

Build Id: f8fd9edc-08a2-450e-91b8-4f1c873a1b3e

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

Kinda just to retrigger ci

agones-bot · 2024-05-17T15:40:37Z

Build Succeeded 👏

Build Id: 69f93d8f-fb98-4d5b-b044-5a0f08e1650f

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://a2d37c5-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3818/head:pr_3818 && git checkout pr_3818
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-a2d37c5-amd64

igooch

Could you please pull in Main and resolve some of what may be merge conflicts?

This reintroduce usage of rooms as a key in lists to show that it is allowed to have the same key name in between list and counters. Also readded initial values for lists as example.

yonbh · 2024-05-21T09:33:05Z

Could you please pull in Main and resolve some of what may be merge conflicts?

This should be resolved now with main pulled in with latest commit of bff72b1 @igooch

agones-bot · 2024-05-21T09:39:50Z

Build Failed 😱

Build Id: ffefc047-1193-430d-9c49-3ab081a6ab56

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

agones-bot · 2024-05-21T10:54:23Z

Build Succeeded 👏

Build Id: ec6ecb14-41b4-4d83-9dea-1b2c1fa5ceaf

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

https://b7497b9-dot-preview-dot-agones-images.appspot.com/

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/3818/head:pr_3818 && git checkout pr_3818
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.41.0-dev-b7497b9-amd64

igooch

LGTM

docs: improve counter and list example comments

5b1d351

github-actions bot added kind/documentation Documentation for Agones size/S labels May 10, 2024

fix: indent

a5a351b

markmandel reviewed May 13, 2024

View reviewed changes

yonbh added 2 commits May 14, 2024 19:53

docs: consistency of counter and list comments between example and re…

1716e09

…ference files Also includes some tidying up of comments

docs: tidy up counter and list spec comments and make consistent exam…

188f491

…ple and reference file

fix: linter requests

c9bed05

markmandel reviewed May 16, 2024

View reviewed changes

feat: make rooms and players example more consistent and remove sessions

1c236a3

yonbh added 2 commits May 17, 2024 19:31

Merge remote-tracking branch 'upstream/main' into docs/improved-count…

a18523e

…er-list-example-comments

feat: remove more sessions mentions and use rooms for counter only

d1e3337

fix: adapt to new templated fleet reference file and make rooms as co…

4afdf72

…unters and players a list

yonbh added 2 commits May 17, 2024 21:57

feat: make fleet reference for player lists more consistent with coun…

e6685e1

…t and list landing page

fix: rooms as counters

804c5a2

feat: use rooms as couters and remove sessions in reference for games…

f2d0b03

…erver

github-actions bot added the size/M label May 17, 2024

fix: indentation

2abdb60

feat: add dot

a2d37c5

Kinda just to retrigger ci

igooch reviewed May 20, 2024

View reviewed changes

yonbh added 2 commits May 21, 2024 17:27

docs: reintroduced more examples for counters and lists

07e491d

This reintroduce usage of rooms as a key in lists to show that it is allowed to have the same key name in between list and counters. Also readded initial values for lists as example.

docs: reuse 333 as capacity value for rooms list

0362020

fix: linter issue

b7497b9

igooch approved these changes May 21, 2024

View reviewed changes

markmandel merged commit 08039d7 into googleforgames:main May 24, 2024
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve counter and list example comments #3818

docs: improve counter and list example comments #3818

yonbh commented May 10, 2024 •

edited

google-cla bot commented May 10, 2024

agones-bot commented May 10, 2024

agones-bot commented May 10, 2024

markmandel May 13, 2024

yonbh May 14, 2024

markmandel May 13, 2024

yonbh May 14, 2024

agones-bot commented May 14, 2024

agones-bot commented May 14, 2024

agones-bot commented May 14, 2024

zmerlynn commented May 16, 2024

markmandel May 16, 2024 •

edited

yonbh May 17, 2024

markmandel May 16, 2024

yonbh May 17, 2024

markmandel May 16, 2024

yonbh May 18, 2024 •

edited

igooch May 20, 2024

yonbh May 21, 2024 •

edited

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

igooch left a comment

yonbh commented May 21, 2024 •

edited

agones-bot commented May 21, 2024

agones-bot commented May 21, 2024

igooch left a comment

	# capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details.
	# capacity: 100

docs: improve counter and list example comments #3818

docs: improve counter and list example comments #3818

Conversation

yonbh commented May 10, 2024 • edited

google-cla bot commented May 10, 2024

agones-bot commented May 10, 2024

agones-bot commented May 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agones-bot commented May 14, 2024

agones-bot commented May 14, 2024

agones-bot commented May 14, 2024

zmerlynn commented May 16, 2024

markmandel May 16, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yonbh May 18, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yonbh May 21, 2024 • edited

Choose a reason for hiding this comment

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

agones-bot commented May 17, 2024

igooch left a comment

Choose a reason for hiding this comment

yonbh commented May 21, 2024 • edited

agones-bot commented May 21, 2024

agones-bot commented May 21, 2024

igooch left a comment

Choose a reason for hiding this comment

yonbh commented May 10, 2024 •

edited

markmandel May 16, 2024 •

edited

yonbh May 18, 2024 •

edited

yonbh May 21, 2024 •

edited

yonbh commented May 21, 2024 •

edited