Need a contributor's guide

[handrews]

As this project attracts more people now that it is active again, we could use some guidance on contributing. I've personally stepped on @awwright 's toes about five times already and I'm sure it's getting just as tiresome for him as it is for me. Things that should go in a contributor's guide:

• How do we resolve issues?

  • How do we indicate that one is accepted, and can move to PR?
  • How do we indicate that one is rejected
  • How do we resolve a conflict- it's clear that there are irreconcilable camps (e.g. $merge/$patch)
  • Closing "orphaned" issues after a "last call" period (two weeks?)'
  • Should implementors implement proposals to try them out, or should we wait until the issue is accepted to some degree?

• Pull requests

  • Any specific requirements?
  • Document that three approvals are required for (new keywords? changes to behavior?)
  • Who is eligible to give approvals?
  • Document that all PRs other than trivial bug fixes will be left open a minimum of 2 weeks
  • Should spec and meta-schema changes always be in the same PR? (I say yes)

• Release process

  • Are some things in-scope vs out-of-scope for the next draft? How do we tell?
  • Is there any way for the community to escalate something in priority? What are good reasons to do so?
  • How do we know when a draft is about to be published?
  • What, if any, additional rules exist during the final pre-publication period?

There's probably more, but these are things that have already come up.

[Relequestual]

I'll hopefully be able to find time to properly reply to this issue next week!

[awwright]

There's few hard-and-fast rules in the IETF model. We believe in rough consensus and running code.

Contributors should come from a diverse background with a variety of use cases. But everyone should try to be thinking about everyone's needs when they propose a change.

More formal implementations and comments should generally be made against the released I-D. At the same time, developers should feel free to work on prototypes and test proposals in running code.

Any issue can be revisited if there's a new reason to.

We use a few tools like GitHub, there's no special requirements, just use it like you would. To the extent GitHub offers a lot of different ways to use it, we're using it for consensus building. Approvals, emojis, and the like are to get rough ideas of the collective mood, and to make sure nobody has been forgotten.

I think the HTTPbis WG in particular should serve as a role model. They've made effective use of their website and GitHub in addition to the traditional mailing list, and have been very careful in writing drafts to avoid locking themselves into a particular design.

---

Anything else is really just a personal (and fairly arbitrary) process. Other people might do it differently, and that's totally valid.

I'll try to make edits and merge PRs as I see consensus. I'll try to give adequate time for people to provide feedback, about two weeks. I'll try to accommodate as many requests as possible, but this may not always be possible. I'll ask for feedback and ask the issue author to close it out to indicate they're satisfied.

Generally, I'm using the spec repo for implementation conserns, the website for guidelines for schema authors and users, and the wiki for a limited amount of guidelines and other notes.

Drafts are used for getting feedback on proposals, so I'll publish a draft whenever I feel there's been a change that needs feedback. I don't want to treat releases as a deadline of some fashion, there's no fixed release schedule, but it should be at least every month.

I'll have limited ability to provide feedback for the next 5 days or so here, but @Relequestual's opinions are just as valid here.

[Relequestual]

The above is one of the reasons I feel that draft 4 should be set in stone as a release version of sorts, because it has much support, and now the project is stepping up a gear in terms of momentum and it would be impossible for implementers to keep up if we release a draft every month.
That's not to say we shouldn't release a draft every month, but equally I feel it's a disservice to the community if there isn't a VERY clear message of ["this is what most implementations will use, and now the development will be more rapid, so draft really means draft now"].

[Relequestual]

(still need to addess the actual issue here)

[awwright]

Also, information about process I've had on the wiki, see https://github.com/json-schema-org/json-schema-spec/wiki

It's more personal notes than anything else, it's nothing contributors are expected to know, especially if they already know how to use GitHub and mailing lists.

@Relequestual There's also #120, I commented the other day about the three-pronged approach website/spec/suite, used for best practices/implementation requirements/backwards compatibility, respectively. That's probably better suited for conserns about what implementors should do.

[handrews]

@awwright I have no idea how to get my concerns through to you. I've written them out in several different issues, in various forms. I've collaborated with @Relequestual to get our shared concerns across. I tried to bring up several sorts of concerns on IRC, which you basically ignored in favor of other topics.

Your "three-pronged approach" is fine for what it is, but does not address my concerns (nor @Relequestual 's, I think, although we have not specifically discussed that point). Your wiki page is definitely helpful with a few things, but not with the larger scale concerns of running the project. And everything here still seems to have to resolve around your rather inscrutable thought process.

I had hoped that you, @Relequestual and I (and anyone else who cared to join in) could collaborate on a mutually agreed-upon framework for progress, but you just keep declaring that you're fine with it as it's already going, or that we should be fine with relying on you for all of the decisions and judgments.

So I guess I will start working on what I think should be happening and see if anyone else buys into it. I really did not want this to be an antagonistic process, but it's clear that you simply won't acknowledge past problems realistically, and that you won't address what either @Relequestual or I am actually concerned about in terms of process here. You've acknowledged that process issues have to be worked out for all projects, but you're resisting working out anything here. So I guess I'll have to propose something of my own.

I don't expect you to buy into it, but at least the rest of us could then have a way to manage our process and resolve things.

[handrews]

@awwright I do want to emphasize that I have tremendous respect for your depth of knowledge and understanding in this area, and the thought / technical leadership that you provide. It is only the area of project management where I am intensely frustrated, and see evidence that I am not alone in that.

[epoberezkin]

@handrews with you on this. We need to manage it properly.

[handrews]

@awwright the numerous commits that you pushed this weekend without any review whatsoever are an example of a serious problem with our lack of process and accountability.

None of us are perfect, all of us make mistakes or miss things (e.g. accidentally deleting "integer" as a type). Your contributions should be as much subject to review as anyone else's, meaning pull requests and 14-day waiting periods. And whatever else we want to put in the process.

[awwright]

These are my personal opinions on the matter:

In general, there's no special rules that contributors are expected to conform to.

The I-D is the primary form for soliciting feedback on proposals, features, and changes; GitHub is used for consensus building.

I generally try to follow the HTTP WG's process, who also uses GitHub and has to deal with a large ecosystem of implementations. But keep in mind RFCs are generally written exclusively over IETF mailing lists.

How do we resolve issues?

Issues on GitHub are run generally as you would expect them, you file an issue, and we work to resolve it to your satisfaction.

For some particularly stubborn contributors, the rest of the community might have to say "that's just not feasible" and we have to close the issue. This scarcely happens, and even then, we can re-examine the issue if there's a new argument or use case that pops up.

Very rarely are there actually two irreconcilable camps. It's something that has to get looked at case-by-case. Generally we'll settle for things like the status quo, fewer features, or erring on the side of security.

On GitHub, I usually close issues after 2 weeks of inactivity waiting for the author to respond to a question. Other people might do it differently.

I would personally love to see every proposal tested in code; there should be experimental implementations following the latest I-D; but the only rule is that two interoperable implementations are required before publication as an RFC.

Pull requests

Pull Requests are a good tool to help with collaboration between multiple authors.

The README.md offers some links on how to work with RFC XML. The prose should be written as a normative standard would be. There's not really a single resource I can refer you to on how to write prose.

As a collaboration mechanism, there's no process for approvals, it seems like a quick way to say "seems fine by me" is all.

There's no fixed timeline for anything, things are moreso dependent on how much feedback we can collect, and leaving issues open is one way to do that.

Edits across documents should typically be made together, but remember a new meta-schema release and a new I-D release aren't necessarily the same thing.

Release process

Since I-D publications are made whenever we need feedback, there's few explicit release goals. I do try to look for features that would be prudent to release together, and I try to solve problems in a logical order -- if problem A is causing problem B, fix problem A first (that seems obvious, you'd think).

The json-schema project is ultimately a community effort and gathering place for implementors to converge on behavior. The I-D is really just a document reflecting that consensus. We can look at any compelling use-case. If someone got a change worked in and they want an I-D released, I can usually do that right away.

I-Ds are used for feedback, so I don't want to treat publications as if there's a deadline that has to be met. I'll usually circulate a document I'm about to upload to try to avoid an embarrassing typo, but it doesn't make any sense to hold off on publication to wait for a feature to be written in, since we can always follow up with another I-D.

[Relequestual]

@awwright I think your last comment has kind of highlighted the issue here. You've decided this is how you will do things, without concern for if the community wants to do things.

Since I-D publications are made whenever we need feedback, there's few explicit release goals.

It's VERY clear, that the community DOES NOT want that to be the case. If you follow the consensus model, you should see, and agree, that the consensus is, we do not want things to continue this way.

You say whenever "we" need feedback, but actually, it's whenever you've determined you want feedback, not when we, the community, have decided. Does that make it clearer where we the community are coming from?

I'll echo @handrews on thanking you for your hard work, dedication, and technical skills. The issue here is if you continue to ignore what the community wants, a defined process beyond "whatever I feel like", then you're going to alienate people.

You may be able to make any edits you wish and release new drafts at will, but doing so shows a sever lack of respect for the community.

Do you agree or dissagree with all of these points?

[epoberezkin]

@awwright, I agree with @Relequestual. Until JSON-Schema RFC exists community will use I-D as a standard, a reference point - both the implementations and end users. There are 100s of implementations and 100s of thousands of users we are talking about. So using it as a feedback tool is highly detrimental to the standard evolution and causes a lot of fear, uncertainty and doubts about the standard future. Following your approach we will get to a point when implementations will have to be explicit about which flavour of the standard (or I-D) they maintain and there will be even wider area where interoperability is lacking than there is already.

With all respect, there are few options here really:

1. you accepts the criticism and change your approach (i.e. there will be no more unapproved PRs / direct commits to master). Publication of I-D should be preceded with at least 2 weeks period where no changes is suggested, meaning that once any change was suggested the timer resets... Last time you published it while I was in the process of reading it and submitting feedback you asked for, which is very disappointing.
2. you step down as a leader
3. standard continues to deteriorate and at some point some other standard is created. How about Functional JSON-Schema? Seems to be trendy now to redefine things by adding "functional" to their names.