Local plugins

[changusmc]

Hello,

I'm going through the example in https://buildkite.com/docs/plugins/writing and trying to create the plugin in my existing local codebase.

Below is the directory structure

file-counter-buildkite-plugin ➤ tree                                                                                                                                                                                      
.
├── README.md
├── hooks
│   └── post-command
├── package.json
├── plugin.yml
└── tests
    └── post-command.bats

In order to use this plugin, I have to add this to my pipeline

steps:
  - command: ls
    plugins:
      - ./ci/buildkite/plugins/file-counter-buildkite-plugin#v1.0.0:
          pattern: '*.md'

Therefore, I want to add that to my README as well.

However, plugin-linter-buildkite-plugin doesn't like my command when I try to validate my plugin

file-counter-buildkite-plugin ➤ docker run -it --rm -v "$(PWD):/plugin:ro" buildkite/plugin-linter --id ./ci/buildkite/plugins/file-counter-buildkite-plugin                                                              git:scratch/changd/buildkite*
lint

Lint a buildkite plugin

Options:
  --id, --name  Id of the plugin (e.g. my-org/my-plugin)     [string] [required]
  --path        Path to the plugin                           [string] [required]
  --readme      Readme filename                  [string] [default: "README.md"]
  --help        Show help                                              [boolean]

--id can not end with -buildkite-plugin. Did you mean ./ci/buildkite/plugins/file-counter?

I also tried versioning it.

steps:
  - command: ls
    plugins:
      - ./ci/buildkite/plugins/file-counter-buildkite-plugin#v1.0.0:
          pattern: '*.md'

file-counter-buildkite-plugin ➤ docker run -it --rm -v "$(PWD):/plugin:ro" buildkite/plugin-linter --id ./ci/buildkite/plugins/file-counter-buildkite-plugin\#v1.0.0                                                      
TAP version 13
ok 1 - plugin.yml is valid
not ok 2 - No readme config examples found with plugin id './ci/buildkite/plugins/file-counter-buildkite-plugin#v1.0.0'. Have you configured the linter with the correct plugin id?
ok 3 - Readme version numbers are up-to-date (undefined)
1..3
# failed 1 of 3 tests
# time=50.012ms

[toote]

@changusmc first and foremost, we're so sorry for the delay on getting back to you!

The issue you mention has a lot of pointy edges. To start with:

• there is an issue with the --id validation that makes it invalid for it to end with buildkite-plugin unless it is a URL
• the --id option should not have the versioning added to it
• there is a bug in the linter that forces the version in the examples even when it is a local plugin

Finally, most of the issues arise from the fact that the documentation now states that you create a folder called file-counter-buildkite-plugin so that you have a git repository with that name afterwards. That is because of agent logic that will add the buildkite-plugin suffix if you specify a plugin as GITHUB_USER/PLUGIN_ID. But you don't have that scenario: your folder is part of a bigger repository and you are using it as part of the repository (in the lingo: a vendored plugin), so it should not have the buildkite-plugin suffix in the folder name. That is what is causing you to run into these (somewhat) bugs.

With all that said, there are several steps that need to be taken:

• make the documentation to write plugins a little bit better for the use-case you are mentioning
• review and correct the bugs in the linter code (note that the last one I mentioned is already solved, but not released)

Once again, we regret it has taken us sooo long to take a look at this, we hope we will do better in the future :)