Feedback from the previous bro-dev thread is now addressed and I’d consider this version of the package manager ready for people to start trying out. Documentation:
* Docs are now hosted at Read the Docs instead of GitHub
I found it more straightforward to setup/use/maintain docs on RtD. It automatically builds docs upon committing to master or making a release tag. See [1] for directions on how the docs could be made reachable at a bro.org domain, but still hosted at RtD.
Which is just my idea of what the process will look like, so please comment if it differs from anyone’s expectations.
* I’ve put it on PyPi [2] and it’s installable via `pip`
What are thoughts on making this the standard installation process for bro-pkg instead of bundling it into the Bro distribution? Benefits:
1) Decoupling from Bro’s release cycle. Seems like the kind of tool where it’s important to have quick/lightweight releases/patches that are easy for users to upgrade to. Would bundling in with Bro make for a more cumbersome upgrade path?
2) Installing via pip will automatically install dependencies (gitpython, semantic-version). Installing those automatically via Bro’s CMake, while probably possible, seems unusual/hacky.
A downside would be that the first-time configuration is currently easier if done via Bro’s CMake since it can fill in all the paths of bro-pkg.config automatically. But I also see potential for addressing that in a way that doesn’t involve putting bro-pkg into Bro’s CMake. E.g. if there were `bro —config site_dir` and `bro —config plugin_dir` commands that could be executed from the command-line, bro-pkg could just use those to autogenerate an appropriate config.
Nice! I like the Quickstart guide, that works now. The How-Tos are
great, too. One suggestion for "Create a Package": I believe the text
doesn't really say anywhere yet explicitly that a plugin can contain
these three different things. Maybe add paragraph summarizing what
"package" actually means at the beginning?
That sounds all good to me. One nit: In (2): the "this" before
repository is ambiguous because (1) talks about a different one.
Looks like this the location where we can also require a couple more
pieces of meta data. I still vote for keeping this minimal, but I
suggest we require at least an email contact and a license statement
before accepting a pull request. I'm torn on requiring a version
number as well: I would like too, but we can't enforce that people
update it as they make changes; and it would just be useless if people
don't. So probably better to skip.
Once this is finalized, do you plan to add a pointer back here from
the BPM docs?
What are thoughts on making this the standard installation process for
bro-pkg instead of bundling it into the Bro distribution? Benefits:
Yeah, I agree, that makes sense. pip is the standard way to install
Python stuff and really straight-forward.
E.g. if there were `bro —config site_dir` and `bro —config plugin_dir`
Good thought, though why not keep it out of Bro: we can add a script
"bro-config" to Bro that cmake populates with the right data. That
would actually be helpful for other stuff as well. That's something we
could still add for 2.5, too.
One suggestion for "Create a Package": I believe the text
doesn't really say anywhere yet explicitly that a plugin can contain
these three different things. Maybe add paragraph summarizing what
"package" actually means at the beginning?
That sounds all good to me. One nit: In (2): the "this" before
repository is ambiguous because (1) talks about a different one.
Changed.
Looks like this the location where we can also require a couple more
pieces of meta data. I still vote for keeping this minimal, but I
suggest we require at least an email contact and a license statement
before accepting a pull request.
Yeah, makes sense to put those bits in the index data, if you decide to require them.
I'm torn on requiring a version
number as well: I would like too, but we can't enforce that people
update it as they make changes; and it would just be useless if people
don't. So probably better to skip.
I agree. We depend on git being the authority for versioning anyway, so requiring people to update a metadata file in addition to creating a git tag still borders on useless even as an enforced rule.
Once this is finalized, do you plan to add a pointer back here from
the BPM docs?
There was one in the main README/landing-page. I added another link in the “Registering to a Package Source” walkthrough. Let me know if there was another place you were expecting to see it, but didn’t.
E.g. if there were `bro —config site_dir` and `bro —config plugin_dir`
Good thought, though why not keep it out of Bro: we can add a script
"bro-config" to Bro that cmake populates with the right data. That
would actually be helpful for other stuff as well. That's something we
could still add for 2.5, too.
Good idea. I’ll get a branch for that today/tomorrow.
Ah, missed that. I think we need to state that more explicitly and
give some more context about this repo being the central hub for the
community to share scripts. Although not sure if the BPM docs are
actually the right place for that then, should that go into the
community section on bro.org?
The “contributing” section [1] feels like one place to put it. Even looks like there’s an old reference to the project there that needs to be updated. I can do that now, but should I add a temporary disclaimer that it’s “not yet open for submissions” or would it be alright at this point if a person came across it and tried to submit a package?
Let's wait until we're ready to announce it. A blog posting would be
good once we believe we have the process down. Before we do that,
maybe we can get a couple people here on this list to give publishing
some of their scripts a try? If that goes well, we start over once
more and announce.