search

ota-meshi / eslint-plugin-yml

This ESLint plugin provides linting rules for YAML.
https://ota-meshi.github.io/eslint-plugin-yml/
MIT License
113 stars 13 forks source link

bug: docs: `flow-sequence-bracket-newline` should only have 1 option #340

Closed jimmy-zhening-luo closed 2 months ago

jimmy-zhening-luo commented 2 months ago

Problem Statement

Today

The documentation for flow-sequence-bracket-newline shows the following Options:

yml/flow-sequence-bracket-newline:
  - error
  - always # or "never" or "consistent"
  - multiline: true
    minItems: null

Same as array-bracket-newline rule option. See here for details. It also states:

Issue

Proposed Fix

Update Options to the following:

yml/flow-sequence-bracket-newline:
  - error
  - always # or "never" or "consistent"
---
# or
yml/flow-sequence-bracket-newline:
  - error
  - multiline: true
    minItems: null
jimmy-zhening-luo commented 2 months ago

Hi @ota-meshi, I am a big fan of your work. I am happy to fix this issue along with #341. However, I have never made an open source repository contribution as a non-organization contributor.

I've created plenty of feature branches etc., but I don't know what the best practice is for creating a PR as an external contributor, even after doing my own research (different sources make different claims to what is considered "correct" or even convention).

Would you be willing to donate 10 minutes of your time to reply to me with step-by-step instructions on how to fix these doc issues? My proposition is that your 10 minutes of time will teach me how to be an open source contributor, and I hope that I will be able to make meaningful contributions to the software engineering community as a direct result of your time.

To show you that I've done my own homework, this is my current assumption:

  1. Fork ota-meshi/eslint-plugin-yml
    • Is this correct? As an organizational (product manager, not engineering) contributor at Microsoft, this was abstracted away from us: for a work item in Azure DeveOps, I would just click a button that sets up my dev environment, make the code change, and then click another button that Submits and kicks off all the necessary reviews and eventual merging.
  2. Create a new branch issue/341/bug-docs-flow-sequence-bracket-newline-should-only-have-1-option (naming convention?)
  3. Apply the code fix I propose in the issue descroption
  4. Commit the code fix to my development branch
  5. ???

Open questions:

  1. How do I unfork? I know I can just "try it", but after reading some of GitHub's own documentation on "creating pull requests" including the section on "if you don't have write permissions", I've been working on software for long enough to be skeptical that their instructions for forking will actually allow me to open a PR against the main branch of this repository, not my own fork. (N.B. Please forgive my impertinence and ignorance: I think forking is a silly model to be honest and is the one part of git that does not make sense to me. It feels like it's solving an authorization issue rather than a source control issue, and in doing so actually creates a huge fan-out of dilapitated cruft that pollutes the Internet / public repository space. Again, this is my bias as a closed source big tech person, but while there are many negative things to be said about big tech, one can't really argue against the fact that Microsoft and Google consistently ship great software and think deeply about the discipline and business of software engineering, so I won't discount my own intuition here, even as I'm begging for your help.)
  2. How do I ensure that the PR I open to fix this issue is actually linked back to the issue? I see that in the GitHub "create PR" interface there's an option to select the issue that the PR is fixing, which again seems a bit flaky to me and is backwards from how every other system I've operated on works (and how I believe it should work): branches are created to fix issues, so they should originate from the issue, both as a matter of UX and as a matter of code-level implementation, where a branch should some how be hash-tied to an issue that spawns it, a more solid notion to me than treating the issue as an arbitrary tag that github.com then knows to display (brittle, non-sensical).
ota-meshi commented 2 months ago

Thank you for posting an issue and considering opening a PR!

In OSS, it's best to fork to open a PR. I think this is mostly for security reasons. This repository uses the master branch as the main branch, but if someone malicious creates a main branch and pushes a virus, someone else might pull it.

After checking out a fork repository locally, you may find it useful to add a remote for the repository it was forked from, with the name upstream. See also https://eslint.org/docs/latest/contribute/development-environment#step-3-add-the-upstream-source

Create a new branch issue/341/bug-docs-flow-sequence-bracket-newline-should-only-have-1-option (naming convention?)

Since the fork of the repository is yours, you can name the branches however you like.

Apply the code fix I propose in the issue descroption Commit the code fix to my development branch ???

After fixing the issue and pushing to your fork of the repository, if you open the GitHub repository in a browser, you should see a link to make a pull request.

How do I ensure that the PR I open to fix this issue is actually linked back to the issue? I see that in the GitHub "create PR" interface there's an option to select the issue that the PR is fixing, which again seems a bit flaky to me and is backwards from how every other system I've operated on works (and how I believe it should work): branches are created to fix issues, so they should originate from the issue, both as a matter of UX and as a matter of code-level implementation, where a branch should some how be hash-tied to an issue that spawns it, a more solid notion to me than treating the issue as an arbitrary tag that github.com then knows to display (brittle, non-sensical).

GitHub will automatically link your commit to the issue if you include an issue number in your commit message, or the top comment in a PR thread:

fix: Short description of what you did

Longer description here if necessary

Fixes #1234

See also https://eslint.org/docs/latest/contribute/pull-requests#step-2-make-your-changes

There are no rules for commit messages or PR titles in this repository. I'm just glad you are opening PR.

How do I unfork?

Sorry, I didn't understand what you meant by "unfork". Want to delete a fork of your repository? I think you can do that in the settings.

jimmy-zhening-luo commented 2 months ago

@ota-meshi thank you! Working on it now.

jimmy-zhening-luo commented 2 months ago

It's been a long day so I am exhausted and don't have a lot of words, but I just want to say I am deeply thankful to you for taking the time to patiently teach me above. You shared a lot of knowledge and wisdom with me.

I'll iterate on these PRs as needed until you approve them.

jimmy-zhening-luo commented 2 months ago

PR draft submitted