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

Add features not to forget to execute finch gen-docs generate -p cmd/finch/ #942

Open
3 tasks
haytok opened this issue May 10, 2024 · 3 comments
Open
3 tasks
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request github_actions Pull requests that update GitHub Actions code

Comments

@haytok
Copy link
Member

haytok commented May 10, 2024

What is the problem you're trying to solve?.
A clear and concise description of the use case for this feature. Please provide an example, if possible.

When we create new commands or options, we need to create command references by executing finch gen-docs generate -p cmd/finch/ on locally.

However, at the moment, the document, pull requests, and CI do not indicate that finch gen-docs generate needs to be run.

As a result, we often forgot to run this command and create reference.

Describe the feature you'd like
A clear and concise description of what you'd like to happen.

  • Documentation
  • Pull Request template
  • CI

We need to add CI to detect whether finch gen-docs generate -p cmd/finch/ is executed by way of 1 or 2 is needed.

  1. Fail the CI if we forget to run finch gen-docs generate, so that when we check the failure, we can run finch gen-docs generate and push the updated references.

  2. Run finch gen-docs generate periodically in CI, create a PR if there are updates to the references, and have it reviewed and merged.

Additional context
Add any other context or screenshots about the feature request here.

Note that this issue is created based on the comments from the following PR.

@haytok
Copy link
Member Author

haytok commented May 10, 2024

Regarding option 1 for the CI, it would involve adding a CI step similar to the following.

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Setup
        uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
        with:
          token: ${{secrets.GITHUB_TOKEN}}

      // Build Finch and Setup VM

      // Generate docs
      // finch gen-docs generate -p cmd/finch/

      - name: Check to generate docs
        run: |
          git add -N docs/cmd
          git diff --exit-code docs/cmd

@pendo324
Copy link
Member

Describe the feature you'd like A clear and concise description of what you'd like to happen.

* [ ]  Documentation

* [ ]  Pull Request template

I'm planning on taking these two, just been sidetracked with other work. I'll try to get a PR posted today.

Regarding option 1 for the CI, it would involve adding a CI step similar to the following.

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Setup
        uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
        with:
          token: ${{secrets.GITHUB_TOKEN}}

      // Build Finch and Setup VM

      // Generate docs
      // finch gen-docs generate -p cmd/finch/

      - name: Check to generate docs
        run: |
          git add -N docs/cmd
          git diff --exit-code docs/cmd

This looks right, but I don't think it'll work well on Ubuntu at the moment. I'm working on #377, so eventually we can probably transition to a Linux runner, but macOS will be easier for now.

@haytok
Copy link
Member Author

haytok commented May 10, 2024

Thanks for the comments!!!

I'm planning on taking these two, just been sidetracked with other work. I'll try to get a PR posted today.

Okay, I'll add the CI (the way of 1).

so eventually we can probably transition to a Linux runner, but macOS will be easier for now.

Thanks!!!
I will use the following link to implement a CI to check doc generation on macos-latest.

@haytok haytok added documentation Improvements or additions to documentation enhancement New feature or request github_actions Pull requests that update GitHub Actions code labels May 10, 2024
haytok added a commit to haytok/finch that referenced this issue May 13, 2024
This fix introduces a new CI to check whether the command reference
documentations need to be updated.

When new commands or options are added, the
`finch gen-docs generate -p cmd/finch/` command should be run locally to
update the documentation.

However, it's easy to forget this step.

An issue has also been created that proposes to detect these differences.

- runfinch#942

Therefore, in this fix, the new CI step will generate the documentation
and compare it with the existing files.
If there are differences, the CI will fail, prompting contributors to
update the documentations.

Signed-off-by: Hayato Kiwata <[email protected]>
pendo324 added a commit that referenced this issue May 28, 2024
…docs) (#960)

Issue #, if available: #942

*Description of changes:*
- Update contribution docs to reflect changes over the past few months: 
   - Windows dev setup
   - Doc updates when commands change


*Testing done:*



- [x] I've reviewed the guidance in CONTRIBUTING.md


#### License Acceptance

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

---------

Signed-off-by: Justin Alvarez <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request github_actions Pull requests that update GitHub Actions code
Projects
None yet
Development

No branches or pull requests

2 participants