state_reason missing from rest api issue docs

[tjenkinson]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://octokit.github.io/rest.js/v18#issues-update https://docs.github.com/en/rest/issues/issues#update-an-issue and probably some of the other issue entries too.

What part(s) of the article would you like to see updated?

state_reason mentioned in https://github.blog/changelog/2022-05-19-the-new-github-issues-may-19th-update/ should be documented.

refs probot/stale#379
refs actions/stale#744

Additional information

It looks like it's actually there but not sure why it's not ended up in the generated page?

"state_reason": {
  "description": "The reason for the current state",
  "type": [
    "string",
    "null"
  ],
  "examples": [
    "not_planned"
  ]
}

is in lib/rest/static/decorated/api.github.com.json.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

@tjenkinson Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[janiceilene]

👋 @tjenkinson If I'm understanding correctly, you're looking to update the Octokit docs, which we don't own. You can open an issue in https://github.com/octokit to request an Octokit update.

It looks like we document this feature in https://docs.github.com/en/issues/tracking-your-work-with-issues/closing-an-issue on the GitHub Docs. I'm going to close this now, but please let me know if I'm misunderstanding your request 💛

Thanks so much for your interest and passion in improving the GitHub Docs ⚡

[tjenkinson]

Ah @janiceilene I put the wrong link. I meant https://docs.github.com/en/rest/issues/issues#update-an-issue

Looks like an issue should be opened on octokit too though (although I think that might scrape these docs)

[janiceilene]

That makes sense! Thanks for the clarification @tjenkinson I'll put this back on the review board for our rest folks to check out 💖

[docubot]

Thank you for opening this issue! Updates to the REST/GraphQL API description must be made internally. I have copied your issue to an internal issue, so I will close this issue.

[skedwards88]

Thanks for this issue! If you navigate to the response schema instead of the example response, you will see the state_reason field as expected. This field isn't required and isn't part of the example response, so you don't see it in the example response.

[tjenkinson]

Hi @skedwards88 for the update command though for the input it says

State of the issue. Either open or closed.
Can be one of: open, closed

So it’s not documented for the request?

[tjenkinson]

@skedwards88 just checking if you saw my reply and if the internal ticket been updated?

[skedwards88]

Thanks for clarifying. I thought you were talking about the response, but I understand now that you are pointing out that this is missing from the request parameters. I'll open an issue for the owning team.

[skedwards88]

state_reason is now documented in the request body as well. Thanks again for this issue!

[tjenkinson]

Thanks! Is the only supported value right now not_planned?

[skedwards88]

Thanks for your thoroughness. I followed up with the team to ask the to define this as an enum and to list the allowed values.

[chouetz]

Hi @skedwards88
sorry to jump back on this issue, I have a question regarding the state_reason.
While trying to work on a related issue, I noticed state_reason cannot be changed alone, and needs an update of state. Do you think this could be mentioned in the state_reason description in the update-an-issue REST API documentation? Something like

---

state_reason string or null
The reason for the current state. NOTE: Can only be updated alongside with a state update
Can be one of: completed, not_planned, reopened,

---

Many thanks in advance

[cmwilson21]

Hello @chouetz! Would you mind opening a new issue for your question? That way I can add it to the board for the team to take a look. 💖