Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document new 7.11 central config vars as Central/Dynamic Configuration #1883

Closed
astorm opened this issue Nov 19, 2020 · 5 comments · Fixed by #1975
Closed

Document new 7.11 central config vars as Central/Dynamic Configuration #1883

astorm opened this issue Nov 19, 2020 · 5 comments · Fixed by #1975
Assignees
Labels
agent-nodejs Make available for APM Agents project planning. docs
Milestone

Comments

@astorm
Copy link
Contributor

astorm commented Nov 19, 2020

When 7.11 of the Elastic Stack is released, update the agent docs for the following config vars to mark them as "Dynamic" (i.e. available in central config). Also possibly label the configuration as dynamic in Kibana X.Y.

@astorm astorm added docs agent-nodejs Make available for APM Agents project planning. labels Nov 19, 2020
@astorm astorm added this to the 7.11 milestone Nov 19, 2020
@trentm
Copy link
Member

trentm commented Dec 4, 2020

This landed in Kibana in elastic/kibana#84678
@astorm @bmorelli25 Does that mean we add the badge to the docs now? Or when 7.11 is in freeze or released?

@astorm
Copy link
Contributor Author

astorm commented Dec 4, 2020

@trentm I'll ultimately defer to @bmorelli25, but my thinking on this is we wait for for 7.11 to be officially released. My thinking around this is based on the following use case

  1. User comes to docs site, sees that this is a dynamic/central config
  2. User goes to the most recently released version of Kibana (7.10) to look for config
  3. User doesn't see this in central config. User is sad.

@trentm
Copy link
Member

trentm commented Dec 4, 2020

I defer to Brandon as well. :)

My preference in reading tech docs is to have "New in version X.Y"-like prose next to things for when they are added. That allows:

  1. A user of an older version of something to read current docs to see what is coming and to be able to tell if something they are reading doesn't apply. E.g. these let me know about things in Python 3.8 and 3.9 even if I'm not quite using that version yet: https://docs.python.org/3/library/zoneinfo.html#module-zoneinfo https://docs.python.org/3/library/sys.html#sys.__breakpointhook__

  2. It also lets us the maintainers add the docs in the same commit as the functionality, which is nice.

That said, it isn't a biggie either way.

@bmorelli25
Copy link
Member

Generally in current, we try to avoid adding references to stack features before that version of the stack releases. But for a lot of different reasons, that's not always possible. In the past, for small changes like this, I've kept a release checklist of doc updates that need to be made before a release. I'm happy to add this one to my list for 7.11.

My preference in reading tech docs is to have "New in version X.Y"-like prose next to things for when they are added

I agree that the "New in version X.Y" or "Added in: vx.x.x", like we currently have in the Node.js APM API reference, is useful -- especially because we only publish a new documentation branch per major.

It also lets us the maintainers add the docs in the same commit as the functionality, which is nice.

For larger, or more complex documentation additions, I agree that this is a great benefit. We have coming soon tags (that render nicely in the docs) that we can add to the documentation in these cases:
coming:[7.11.0,This feature will be available when version 7.11 of the Elastic Stack releases.]. You can read more about them here.

@trentm
Copy link
Member

trentm commented Dec 4, 2020

Brandon,

Thanks! A release checklist for this sounds fine to me. We have this ticket already on our 7.11 milestone. I'll morph this one to cover all the of config vars being added to central config.

@bmorelli25 bmorelli25 self-assigned this Dec 4, 2020
@trentm trentm changed the title Document TRANSACTION_IGNORE_URL as a Central/Dynamic Configuration Document new 7.11 central config vars as Central/Dynamic Configuration Dec 9, 2020
@trentm trentm assigned trentm and unassigned bmorelli25 Feb 9, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
agent-nodejs Make available for APM Agents project planning. docs
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants