feat: create and list issues

[kavitha186]

This PR is for the feature to post issues on the repositories with shepherd. if you are looking to post issues across multiple repositories, you can use the command "issue" to create, update , list posted issues and close issue

issue with the title, issue message, labels , state and state_reason provided in the migration scripts.

This enhancement feature is for the issue https://github.com/NerdWalletOSS/shepherd/issues/87 and https://github.com/NerdWalletOSS/shepherd/issues/590

Screenshots

Create Issue

Update Issue

Closing Issue

List Issues

Screencasts

https://github.com/NerdWalletOSS/shepherd/assets/17735710/2f21596f-a943-4480-a1ce-dd0fdbfaf5f8

[aorinevo]

@kavitha186, we need unit tests to cover issue, list-issues, and list commands. Can you add those?

I've started down this road with checkout.ts. Seems a bit bulky and in need of rework but thought I'd share how I'm thinking about adding coverage for commands.

https://github.com/NerdWalletOSS/shepherd/pull/697

[aorinevo]

@kavitha186, I've landed test coverage for all the existing commands. You should be good to go to do the same for the new commands introduced in this PR.

[aorinevo]

@kavitha186, let’s add a screenshot of unit tests coverage. A recording demoing the functionality would be helpful too.

[kavitha186]

@kavitha186, let’s add a screenshot of unit tests coverage. A recording demoing the functionality would be helpful too.

[kavitha186]

[>]( Uploading Screen-2024-03-17-185925.mp4… ) > @kavitha186, let’s add a screenshot of unit tests coverage. A recording demoing the functionality would be helpful too.

Uploading Screen-2024-03-17-185925.mp4…

[aorinevo]

CI is failing due to linting errors.

[kavitha186]

CI is failing due to linting errors.

fixed

[aorinevo]

I think we're in the final mile and very much looking forward to landing these changes. There are a couple of things left to address:

1. There are a few type errors to resolve which is causing the builds to fail. Can we look into that and resolve them?
2. When calling the list-issues command, we should include the state of the issue (e.g., closed, open, etc...). Can we add that?

[aorinevo]

@TheSavior and @kavitha186, thank you for your continued feedback and contributions. While I think we've diverged a bit from the requirements Eli is after, I think Kavitha's foundational work is valuable and potentially adjustable to include Eli's use case.

Use Case To align, let me summarize the use case we're after, leveraging Eli's example. Say there are 5 issues that we are scanning for in repos. If they are auto-fixable, we fix them via a PR. For those issues which are not auto-fixable, we want to create an issue with a description that potentially contains data unique to that repo.

Current State There are two checkout related hooks that are exposed via Shepherd's migration-spec file: should_migrate and post_checkout. The should_migrate hook executes when a repo is checked out to determine whether to keep the repo. If successful the repo is kept and subsequently the post_checkout hook is executed. If should_migrate is unsuccessful, the repo is removed and post_checkout is not executed.

If post_checkout is successful, the repo is kept. Otherwise, the repo is removed.

Solution 1 (Recommended) Effort: Low

1. Leverage should_migrate a. Instead of checking strictly whether or not the repo is auto-fixable for all 5 issues, we leverage this hook to generate the data to feed into the post_checkout step. To make the data available between hooks, we can persist state to disk.
2. In the post_checkout step, we can read in the data and use it to take decisions on what issues to create and incorporate repo specific data into the issue details.

Pros: No code change required to Shepherd Cons: End user has to persist and manage state on disk

Solutions 2 Effort: Medium

1. Similar to the recommended solution but we expose a singleton that can be used to pass state between hooks.

Pros: End user does not need to persist and manage state on disk Cons: This state will only be accessible to hooks attached to the same command.

Solution 3 Effort: High

1. Similar to Solution 2 but Shepherd persists and manages state on disk.

Pros:

 - End user does not need to persist and manage state on disk.
 - End user can leverage state across hooks and commands.

Cons:

 - We take a performance hit by reading/writing to disk.

[aorinevo]

@kavitha186, while I did some research on existing tooling to ensure we're not overlapping with feature sets already available elsewhere, I think it would be valuable to double check from your end.

For example, does gh cli tool offer issue creation and management across multiple repos?

Just curious if there is anything we might have missed.

[kavitha186]

@kavitha186, while I did some research on existing tooling to ensure we're not overlapping with feature sets already available elsewhere, I think it would be valuable to double check from your end.

For example, does gh cli tool offer issue creation and management across multiple repos?

Just curious if there is anything we might have missed.

I see there is a gh cli command to post issue or create PRs. Perhaps that is available only to manage a single repo as far as I see.

[TheSavior]

Option 1 seems fine tbh, happy to persist things to dish. It seems like there is some information I couldn't easily get from just a user script running in should_migrate though. For example, in order to form those URLs, I'd need to know the org/repo name. I could probably shell out to git remote and figure it out, would that be your recommendation? I would also probably need that to key the data stored on disk to the right repo so that when the issue hook runs later I know where to look for that persisted repo info.

[TheSavior]

Oh or maybe your point about the gh cli is that I should just use shepherd to search and filter the repos, and once I get to should migrate and run the custom script, that script should just call the gh cli. That would probably work too!

[aorinevo]

Oh or maybe your point about the gh cli is that I should just use shepherd to search and filter the repos, and once I get to should migrate and run the custom script, that script should just call the gh cli. That would probably work too!

My comment is with respect to adding the issues command to Shepherd. That said, I think calling gh within your shepherd scripts would suffice for your use case.

[kavitha186]

[aorinevo]

@kavitha186, can we address the CI failures?

[aorinevo]

@nwalters512, would love your input and feedback on this PR when you get a chance.