Add CONTRIBUTING.md and clarify maintainer status

[goerz]

Continuing #22 (comment), we should probably clarify roles and responsibilities, and who will do things like merge PRs or handle the registration of v1.0.0.

I still think @mofeing would be the most natural maintainer of the package, going forward (in which case we'll adjust this PR to reflect that).

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.88%. Comparing base (3522d66) to head (475ea4d).

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #25   +/-   ##
=======================================
  Coverage   84.88%   84.88%           
=======================================
  Files           2        2           
  Lines          86       86           
=======================================
  Hits           73       73           
  Misses         13       13           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[goerz]

@scheinerman @mofeing Thoughts?

[goerz]

I have a whole lot of opinions on this: https://michaelgoerz.net/notes/inter-release-versioning-recommendations.html, but this is entirely up to whoever ends up the maintainer, with authority of this. Or, we could just not say anything in these guidelines.

[mofeing]

Contributors may increase the version for a fast release, but I prefer them not do deal too much with the versioning and leave it to the maintainer.

Suggested change

3. Consider increasing the version number in Project.toml according to [SemVer](http://semver.org/), with a `-dev` suffix.

[goerz]

This, again, is super opinionated, and probably nobody else does it this way. I like it though, and it's what I would do if I was managing releases. If someone else is managing releases, they can do whatever they want and we can adjust this text 😉

[mofeing]

I think this is the correct way for larger and more complex sofware like Julia itself. But for a small package like Bijections, this is very cumbersome. Most of the times is just a patch version update and calling the registrator.

[goerz]

As far as I'm concerned, this is the last step before we can think about whether there's anything missing in order to tag v1.0.0, and, if not, start preparing that release.

[scheinerman]

Hi @goerz : Here's the issue. I'm happy to serve as a resource for Bijections be that as a maintainer or a co-maintainer. I'm OK as an approver.

But here is my concern. If changes are made, I know how to update the Project.toml file to a new version number, and how to trigger a registration. If there is anything more that needs to be done, then I'm lost. My experience in all this tells me that I'm not suitable for all the git magic. The only up side was the superb attention I got from you (and @mofeing) to make this happen. But I don't want to do all the rigamarole again!

[goerz]

Sure, I understand, which is why I think @mofeing should take over as the main maintainer if he has any interest in doing further development on this package in the future.

Another possibility is that we don't go too deep with describing workflows in CONTRIBUTING.md, and I and @mofeing just make some more direct PRs/ commits to prepare for v1.0.0 to get you to the point of triggering the release.

Unless @mofeing wants to do more development, since you don't have plans for touching the package in a significant way, it's pretty likely that the package is going to sit there unchanged after the v1.0.0 release.

So it's really up to @mofeing to either step in or not. If not, I think I'll just look over everything in the next few days, get it ready for v1.0.0, and let @scheinerman tag that release, and then we'll just let the package stay as "done" for the time being :-)

[mofeing]

Okay, given that I was going to register BijectiveDicts.jl, I can step up as (co-)maintainer of the package. I would be glad if you're still around to take some decisions.

But here is my concern. If changes are made, I know how to update the Project.toml file to a new version number, and how to trigger a registration. If there is anything more that needs to be done, then I'm lost. My experience in all this tells me that I'm not suitable for all the git magic. The only up side was the superb attention I got from you (and @mofeing) to make this happen. But I don't want to do all the rigamarole again!

Don't worry. I think @goerz and I can take care of that.

Another possibility is that we don't go too deep with describing workflows in CONTRIBUTING.md, and I and @mofeing just make some more direct PRs/ commits to prepare for v1.0.0 to get you to the point of triggering the release.

I've never been to keen on writing a CONTRIBUTING.md, but not against it.

So it's really up to @mofeing to either step in or not. If not, I think I'll just look over everything in the next few days, get it ready for v1.0.0, and let @scheinerman tag that release, and then we'll just let the package stay as "done" for the time being :-)

Yeah, even the features I'm planning are just a few (mainly the Serialization integration) and can be added later as a minor release. I think we should be able to get a v1.0.0 release fairly fast.

From my side, one thing left that we should take care of before v1.0.0 is this method:

Bijections.jl/src/Bijections.jl

Lines 159 to 162 in 3522d66

	function inverse_dict_type(D::Type{<:AbstractDict{K,V}}) where {K,V}
	@warn "Using the default `inverse_dict_type` for $D. This may not be optimal for your specific dictionary type."
	D.name.wrapper{V,K}
	end

It does some internal hacking we shouldn't rely on. I added it because it was useful for BijectiveDicts.jl, but now that we are taking it more seriously, we should remove it and write extensions to that method for different dict types.

@scheinerman Also, Are we sure we want domain and image to return iterators? Maybe we can make them return Set (or IdSet if it's using a IdDict) and use Base.keys and Base.values for the iterators. IMO I don't really see the point of domain and image, but it may break existing code that uses Bijections (but the examples I've seen they don't use it).

[scheinerman]

Thanks. The only contribution I might consider going forward is light editing of the documentation, but I really think this package is "done".

By the way, the git website shows this as release 0.2.1 but the version is actually 0.2.2.

[goerz]

Great, so then I've now put @mofeing as the "current maintainer", and as the person responsible for tagging releases. On that note, according to the Registrator README, it's apparently sufficient to have "Contributor" permissions in order to tag a release. Nonetheless, it would probably be good for @scheinerman to elevate the permissions of @mofeing to at least "Maintain", if not "Admin". I'm not going to need any higher permissions that what I have now, I would think.

I've never been to keen on writing a CONTRIBUTING.md,

It's probably somewhat optional, but it's usually a good idea to document some basic workflows. Now that we've hooked you as the person who will tag releases, please feel free to make changes to the CONTRIBUTING.md in this PR to reflect whatever process you want to follow – or, no specific process if you just want to remove some of these details.

one thing left that we should take care of before v1.0.0 is this method […] Also, Are we sure we want domain and image to return iterators

Sure, go ahead with any PRs you feel would be good to have and/or any testing that should be added to increase the coverage, if that's something anyone cares about.

With that, I pretty much leave it to you guys to finish up the v1.0.0 release. I'm happy to do a quick review on any PRs in the meantime, or if you need anything else, just ping me.

I definitely do think we should tag v1.0.0 relatively soon, though. I'm holding back on the next DocumenterCitations release until then, see JuliaDocs/DocumenterCitations.jl#95 (comment), so that I can directly include 1.0 in the compat specs for Bijections.

[goerz]

By the way, the git website shows this as release 0.2.1 but the version is actually 0.2.2.

Just fixed that. It should (hopefully) work automatically going forward, with TagBot taking care of this.

[scheinerman]

@mofeing : Just for amusement (and totally off topic here): The f and finv fields in a Bijection can be any type of AbstractDict. And a Bijection is, itself, an AbstractDict. So can f or finv be a Bijection? I can't imagine why anyone would do that! No reason to modify anything. It just occurred to me and made me laugh a bit!

[mofeing]

I've never used the CONTRIBUTING.md file because I prefer to give a lil more of freedom to contributors, but that's my way with my packages and since this package can affect some part of the ecosystem, I'm okay with following some standard practices within the community.

I would remove the "release process" section because that should be done by the maintainer and not by other contributors.

[mofeing]

Contributors may increase the version for a fast release, but I prefer them not do deal too much with the versioning and leave it to the maintainer.

Suggested change

3. Consider increasing the version number in Project.toml according to [SemVer](http://semver.org/), with a `-dev` suffix.

[mofeing]

I think this is the correct way for larger and more complex sofware like Julia itself. But for a small package like Bijections, this is very cumbersome. Most of the times is just a patch version update and calling the registrator.

[mofeing]

@mofeing : Just for amusement (and totally off topic here): The f and finv fields in a Bijection can be any type of AbstractDict. And a Bijection is, itself, an AbstractDict. So can f or finv be a Bijection? I can't imagine why anyone would do that! No reason to modify anything. It just occurred to me and made me laugh a bit!

You can! No idea when this ever would be useful but yeah, it's funny.

julia> d = Dict(:a => 1)
Dict{Symbol, Int64} with 1 entry:
  :a => 1

julia> b = Bijection(d)
Bijection{Symbol, Int64, Dict{Symbol, Int64}, Dict{Int64, Symbol}} with 1 entry:
  :a => 1

julia> bb = Bijection(b, inv(b))
Bijection{Symbol, Int64, Bijection{Symbol, Int64, Dict{Symbol, Int64}, Dict{Int64, Symbol}}, Bijection{Int64, Symbol, Dict{Int64, Symbol}, Dict{Symbol, Int64}}} with 1 entry:
  :a => 1

EDIT: After thinking, this can be a way to get a multi-bijector. Like the domain set can be linked one-to-one to more than one image set. This is probably not optimal but it's fun to see it like this.