search

json-schema-org / json-schema-spec

The JSON Schema specification
http://json-schema.org/
Other
3.79k stars 266 forks source link

Need a contributor's guide #137

Closed handrews closed 7 years ago

handrews commented 8 years ago

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:

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

Relequestual commented 8 years ago

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

awwright commented 8 years ago

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 commented 7 years ago

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 commented 7 years ago

(still need to addess the actual issue here)

awwright commented 7 years ago

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 commented 7 years ago

@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 commented 7 years ago

@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 commented 7 years ago

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

handrews commented 7 years ago

@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 commented 7 years ago

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 commented 7 years ago

@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 commented 7 years ago

@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.
awwright commented 7 years ago

@epoberezkin Thanks for your feedback, I hope you can trust that it's very useful and I'm aware of many of the problems.

I'm in constant communication with @Relequestual and we've settled on a process where most changes where most changes will wait for PR approval by a second party.

There's still a handful of issues I'm facing in the document editor role.

The process through which we're publishing has specific conditions on usage:

The Internet-Drafts repository is available to provide authors with the ability to distribute and solicit comments on documents they may eventually submit for publication as an RFC. I-Ds are not an archival document series. I-Ds should not be cited or quoted in any formal document, except as "work in progress". Unrevised documents placed in the I-D repository have a maximum life of 185 days. After that time, if I-D is not updated, it will be deleted.

This limitation is formalized in other standard's groups processes. I've had two people contact me asking about a timeline to RFC, saying they need a media type registered, and a standards-track document to cite -- I-Ds are specifically not citable. I've also seen talk at the W3C, who also requires an RFC to cite. I very strongly feel we need to accommodate these people.

In my earlier personal opinion I said I don't want a fixed timeline -- but there is at least one required deadline, the 6-month expiry date. So basically we're in a position where if we want JSON Schema to see widespread adoption, we need an RFC, and by extension, we need to be regularly releasing I-Ds.

The IETF rules don't mean that I-Ds are unsuitable for implementation. Quite the opposite, most I-Ds are developed in an iterative process alongside implementations, I cite HTTP as an example. If you have any conserns that this process isn't suitable for JSON Schema, can you go over some specific details?

Finally, if you actually do think the standard has deteriorated, I highly encourage you to provide specific details.

handrews commented 7 years ago

we've settled on a process where most changes where most changes will wait for PR approval by a second party

Thank you. Could you please detail what "most" means so that there is no confusion? Sometimes even minor wording changes can have major impact on a specification.

There's still a handful of issues I'm facing in the document editor role.

What are your issues exactly? The rest of your comment just generally says that we need to keep releasing drafts at least every six months and get to RFC status. That's not a process for how we as a community works, that's just the bare minimum requirements of writing a standard.

I have started the work of defining the scope of v6 on the mailing list. This is to focus our efforts and get a v6 out soon instead of just wandering about in all of these issues, some of which are not going to get resolved anytime soon.

For v6 core, I think the only thing we need to resolve is whether we're just renaming id to $id or whether we are splitting it into $base and $anchor ( #20 / #154 or my preferred option #149 / #155 ). We could defer that, but really we have enough info and participation to make a call on those right now.

I will go ahead and send out v6 scope proposal emails for validation and hyper-schema. Then we can focus on resolving the things that need to be resolved before v6 goes out.

epoberezkin commented 7 years ago

@awwright thank you for the answer, it is good that we are converging to some consensus.

The process through which we're publishing has specific conditions on usage

I understand that. Yet, given more official status of those documents and the effort required to publish them than the status of docs in github repo, the community would still see them as de-facto standard and while we can use them to collect feedback for the standard evolution (new features and changes) we need to put a sufficient effort into ensuring that these documents are thoroughly reviewed and corrected before they are published so they can continue to serve as standard for implementations and users.

So basically we're in a position where if we want JSON Schema to see widespread adoption, we need an RFC, and by extension, we need to be regularly releasing I-Ds.

I don't see any contradiction here. We can have a very high quality of I-Ds published every 6 months if we allocate say 2 months for review process.

If you have any concerns that this process isn't suitable for JSON Schema, can you go over some specific details?

As I wrote I think that they should be suitable and that's why we should put more effort into reviewing them before publication.

if you actually do think the standard has deteriorated, I highly encourage you to provide specific details.

Firstly, the draft 4 is already implemented inconsistently in the area of $ref resolution and that was the reason for my multiple proposals to simplify it. There seems to be little real value in supporting base URI change within the document (I don't know anybody who uses it) and yet you insist on its importance.

Secondly, I refer to multiple corrections and clarifications that are required after the latest publication. E.g. losing integer type. Or accidentally changing the meaning of some keywords. Whoever tries to implement the standard now, while precisely following the latest draft, will end up with incompatible implementation. So I think, as I wrote in another thread, I believe that v6 should deliver on the promise of "correcting/clarifying/improving language without any functionality changes" to provide a stable and backwards compatible point for the implementation authors who are not aware of our current transitional state. And I think that it should happen sooner than in 6 months. The longer we wait the more chance we have of having incompatible implementations (which is the main indicator of the standard decay). @Relequestual @handrews @awwright do you agree with publishing another I-D with fixes?

awwright commented 7 years ago

@handrews I hope I made the argument, though, that we need RFC status if we're going to be taken seriously, and why that necessitates moving away from the model we were using before -- where there's only 2-3 authors, treating the I-D as a standard, and publishing infrequent updates and allowing it to expire.

handrews commented 7 years ago

@awwright In what way did I contradict any of that?

handrews commented 7 years ago

@epoberezkin I'd like to just wrap up the changes and fixes we have so far plus a few more (we need to do something about unusable bits of hyper-schema- I will cover that in my v6 hyper-schema scope email later today).

I don't think it's useful to back out all of the features and just do a bug fix release. We can get a v6 with the currently added features out very quickly with a bit of focus. Which is why I am trying to get us to agree on a scope, and then get it done.

epoberezkin commented 7 years ago

@awwright I have no objection to making it RFC. I am just saying that until that time we should treat I-Ds as seriously. We are not talking about 2-3 authors now, we are talking about 100s of packages relying on the spec.

awwright commented 7 years ago

Right now the opinion seems to be nicely put by @epoberezkin:

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.

But this is explicitly prohibited by the I-D process.

My solution is to use the website to for general reference, instead. I'm working on revamping the "documentation" section to focus on schema authors, and then assisting implementors.

epoberezkin commented 7 years ago

@handrews if that's the case I think we should limit the scope to the features that have been thoroughly discussed and agreed and have this draft backward compatible with draft4. Ideas like $base, $combine, $use, $merge, $id, etc. I would keep out of this scope.

awwright commented 7 years ago

@Relequestual heads up pull requests for the website, and @Julian the test suite, @Relequestual is on board with expanding the website to cover a lot of the cases that I think the I-D shouldn't be.

epoberezkin commented 7 years ago

@awwright:

My solution is to use the website to for general reference, instead. I'm working on revamping the "documentation" section to focus on schema authors, and then assisting implementors.

Website points to the I-D for the reference. Even if we include the reference page directly into the website, having it in any way different from I-D is just more FUD - people will be confused. Even if you add note that website is the reference point, people may miss it and by default would treat I-D as the source of truth. I don't understand the insistence of using it in any other way.

awwright commented 7 years ago

@epoberezkin People don't go to the HTML specification to learn HTML, people don't go to the JSON reference to learn JSON, people scarcely even go to the HTTP reference to learn about HTTP (though I definitely think they should)... In many of these cases, I think that's perfectly justified. A specification, and the JSON Schema specification is no exception, has a lot of contrived examples to demonstrate all the corners of functionality, that wouldn't be reasonable in a regular document.

Also, RFCs aren't the easiest things to read, even after you've pushed them through the HTML processor. I think we can do a lot better job expanding the website, and leave the I-D for implementors.

It's easier to show you what we've got, I'm not even writing up content so much as I'm trying to make the documentation look beautiful, so I'd like to ask we wait until I can show a working PR for that end.

epoberezkin commented 7 years ago

@awwright:

People don't go to the HTML specification to learn HTML, people don't go to the JSON reference to learn JSON, people scarcely even go to the HTTP reference to learn about HTTP (though I definitely think they should)...

People don't. Implementers of tools do.

If one wants to use JSON schema they would read tutorial. If one wants to create a validator they would read I-D. Inconsistency in tools implementation causes standard deterioration.

Actually, even users of Ajv were pointing me to I-D as the source of truth in many issues (e.g. lack of clarity about patternProperties validation).

handrews commented 7 years ago

if that's the case I think we should limit the scope to the features that have been thoroughly discussed and agreed and have this draft backward compatible with draft4. Ideas like $base, $combine, $use, $merge, $id, etc. I would keep out of this scope.

@epoberezkin did you read my email? This is exactly what I'm trying to do (except $id because renaming it was already approved in the issue and $base/$anchor should be a simple enough yes or no at this point- if it's not we'll definitely defer it, but the discussion is moving along at a nice pace right now).

All of the other things you mentioned are out of scope.

people scarcely even go to the HTTP reference to learn about HTTP (though I definitely think they should)

@awwright LOL yes.

epoberezkin commented 7 years ago

@handrews nope. Which email?

handrews commented 7 years ago

@epoberezkin https://groups.google.com/forum/#!topic/json-schema/eQ-s3AIYd1U which only covers core. I will send out validation (which I think just needs its open PRs resolved) and hyper-schema (which will probably be contentious) today, assuming I don't spend all afternoon responding to issues here :-)

handrews commented 7 years ago

I could also just file the email contents in an issue. I was trying out having general discussions on the mailing list so we could reserve issues for actionable steps. Given how little traffic the mailing list gets I'm not entirely sure what it's for.

handrews commented 7 years ago

@epoberezkin : I have sent out the other road map emails. Since I have dropped PR #155 (which was the only controversial part of the v6 core road map that I proposed), I think we could do a v6 draft just by resolving a few PRs, only one of which is likely to be controversial.

Of course this is just me totally making up the list of things that I personally think should make it into v6 and should not be considered authoritative. But I did follow your request to minimize the scope. Here's what's left to go in (all PRs, not issues):

Core PRs:

154 deprecate id in favor of $id

Validation PRs:

128 boolean subschemas everywhere

143 general validation principles (I removed the controversial part of the change)

150 "uritemplate" and "jsonpointer" formats

Hyper-schema PRs:

159 User input for URI Tempates with "hrefVars"/"baseVars", remove "method", use "schema" and "encType" for request body only.

Note: PR #129 is NOT in scope for v6 and is not necessarily accepted at all at this time.

The hyper-schema one is obviously the one we'll have to discuss and no doubt revise as I just wrote it very quickly. It is based on a proposal @awwright floated on IRC as a less controversial first step towards more comprehensive hyper-schema improvements. I'm not sure if he was seriously comfortable with it or just vaguely contemplating it, but I figured I'd go ahead and write it up. Have at it! :-)

handrews commented 7 years ago

OK. I've looked back over the conversation now that I'm not frantically trying to respond to each comment and also get that one hyper-schema PR posted.

I'm going to try to synthesize the various concerns into a process proposal. @awwright @epoberezkin @Relequestual please let me know whether you think this is a productive approach.

@awwright Your ideal process would be a draft "at least every month", and your concern is is that you do not want to hold up the public feedback cycle which relies on draft publication.

@epoberezkin You mentioned at least a 2-week review freeze, but also talked about even a 2-month review period.

My biggest concerns are around focus and managing the set of open issues. I want clear communication, transparency, and a welcoming community. (er... yes, I know I'm not always the most easy-going, welcoming person, so do feel free to call me on that!)

Managing and reviewing draft releases

Let's start with balancing release frequency and review. There's a really simple solution here which is to use branches for pipelining. git-flow is a bit heavyweight and complex, while GitHub-flow is for continuous deployment which doesn't fit either.

What I recommend is a simple two-branch system. One branch is for active development work, while the other is for review and release (one of these can be master, I don't care which is which).

We open pull requests against the development branch, and merge them as they meet whatever review threshold we establish (more on that later). When we think there's enough for a new draft, we tidy up the release notes and then push the contents of the development branch to the review/release branch.

The release branch only accepts bugfixes- spelling and grammar corrections, clarifications that don't change the functionality that was agreed to before. People look at this to review the specification as a whole for consistency and clarity. This is also where proper wording, tone, and IETF/IANA confomrance gets double-checked. When it looks good, we tag a release and submit the new draft.

While that review is going on, active work continues on the development branch. Some people might focus on the last review, others will focus on the leading edge of work. Whenever the draft under review gets published, we can immediately push the next batch out for final review. So even if we mandate a 2-week final review period, we could in theory publish a draft every two weeks.

Reviewing pull requests

All change to the specification documents that are more complex than a spelling error get a PR, even if you have write access. It's too easy to accidentally omit or add a word that dramatically changes the meaning of a spec. Everyone does it sooner or later.

Changes that are not intended to affect the functionality of a spec need one approval from someone who has been around the project long enough to be recognizable. So if you post a PR that fixes the wording of a paragraph, it will probably get approved and merged very quickly.

Changes that affect the functionality of the spec need multiple (2 or 3?) approvals from people who have demonstrated an understanding of the project, and need to be visible for review and comment for some minimum period of time (we currently seem to be using two weeks). If we need three, maybe only two need to be from "contributors". The contributor reviewers would probably be the four of us participating in this issue plus Julian and whoever else meets whatever criteria we come up with? Where there are concerns over conformance with IETF standards and practices, someone with knowledge in that area (presumably @awwright, not sure if anyone else here qualifies- I do not) needs to approve it.

There should be some flexibility here- if the change is directly putting words from a thoroughly discussed issue into the spec, maybe it only sits for one week.

Focusing our efforts

There are a lot of issues and proposals floating around, many of which are years old. And we all keep adding more. We need to put a concerted effort into working through them. They tend to clump around themes- id, format, object properties, and hyper-schema in general are a few big ones off the top of my head.

Instead of us all going around and poking at whatever catches our fancy, we should, as a community, pick a theme or two and focus on resolving all of the open issues in those themes. I'm sure we'll pick up various small things along the way, and keep nudging some of the more contentious longer-running issues in the background.

But for instance, I'm hoping to get id resolved in v6, or at least resolved enough to close the current batch of issues ( #14 and #20 are the ones still open). In general I'd like to try to resolve core issues ASAP as they provide the foundation for the vocabularies. Validation is the one that most people focus on, so it moves along well- it just needs some focus to work out all of the overlapping and competing proposals. And hyper-schema needs the most thought and effort- I'm implementing a client right now which is already helping to flush out issues (#157, for instance).

So, what I want is an ongoing process of picking a focus and, um... focusing on it :-) That doesn't prevent anyone from doing anything else, but does set the top priorities of the group and keeps us from flying in all directions as we (hopefully) have more people joining us. It will also be satisfying for implementors to see specific confusing areas as fully resolved as possible, instead of a few tweaks here and there but nothing really brought to closure.

If we can decide on the v6 scope (whether what I proposed above or some modified version of it) then I can start email threads or issues (do we even want to use the mailing list?) to propose and discuss the v7 scope. I've done plenty of project management so this is familiar territory for me.

So... I don't really have a nice conclusion here. Those are my suggestions and my attempts at reconciling competing goals. Thoughts?

epoberezkin commented 7 years ago

@handrews The only thing I disagree with is changing id into $id without changing its meaning. If we later change its meaning, and there is some indication that we may (#14, e.g. and other discussions - I am going to submit one more proposal how we can resolve our referencing mess and get feedback from more than 4 people here) it would be better to change the keyword at the same time. That would reduce confusion and simplify everybody's life: id would mean A, $id - B. With your approach we would have that $id can mean both A and B depending on which I-D draft schema author or implementation was relying on. So I suggest avoiding this situation.

handrews commented 7 years ago

@epoberezkin if your new submission looks like it's getting traction, we can drop $id from v6. But if not, unless you can get as similar number of people who backed the change to $id to agree with you, $id should go in v6. This is not exactly a new argument and no one person should be able to veto progress that already got broad buy in

epoberezkin commented 7 years ago

@handrews re change process it's all ok, although I don't follow what's the need to release I-D every two months? @awwright wrote it should be every 6 months I think.

It would also help adding contributions guidelines (not the process) so that whoever submits the issues / PRs follows some patterns. ESLint for example has very good structure of contribution types.

Relequestual commented 7 years ago

All of the above seems sensible and reasonable to me.

To address one issue raised, we agreed that PR is always required unless it's a typo or spelling or something gramatically obvious.

On a different issue, organisation of issues is a problem. I create a draft 6 milestone. Happy to add issues to that where deemed appropriate. Adding PRs and issues to such would make a changelog easier also, unless you're writing that as you go.

In terms of better managing issues, sane labeling could help (https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63#.cu5kuac7u) - I agree the default labels are somewhat sucky. I can't make the time to set those up this week, but I may find some extra time soon.

I'm going to assign myself to this task, for the above, and for making a contributors guide, PR template, and issue template.

I'll also state that for this task to be closed, new issue tags must be created, and an issue created to attempt to tag all issues.

It's a shame you can't give people the ability to tag issues without write access to the repo. @awwright I'm happy to add @handrews to the spec team if you agree.

Relequestual commented 7 years ago

I don't know if this is a good idea or not, but:

A repo with only issues, for implemetors, in which we invite as many implementors as possible to become collaborators, and use issues to announce feedback illicitation period before I-D publication. Thoughts? I was thinking this because currently it's difficult to reach implementors... I don't think the google group covers this usecase.

epoberezkin commented 7 years ago

@Relequestual What's the risk of having all implementors as collaborators in this repo? Everybody will follow guidelines. You also can prevent direct commits to master, but at least it would simplify commits to feature branches (it's a bit easier to push to branches than to forks).

handrews commented 7 years ago

I actually prefer working through a fork unless the branch needs to be shared.

It's a shame you can't give people the ability to tag issues without write access to the repo. @awwright I'm happy to add @handrews to the spec team if you agree.

If either of you are uncomfortable with me merging things, I'd be happy to just restrict myself to managing tags/labels/milestones/review branch logistics/etc. Otherwise I will tend to look to a documented process as to when we've met the criteria to merge PRs, and if it is at all ambiguous I would hold off.

Relequestual commented 7 years ago

@epoberezkin I was planning to cast the net wide regarding implementors... I know for a fact that there are some implementations out there which I wouldn't touch...

Relequestual commented 7 years ago

I prefer to always fork and pull request also!

@handrews I have no reservations about giving you full write access to both the spec and site repo, and expecting you to use it.

handrews commented 7 years ago

Thanks! The advantage of using a fork, to me, is the ability to rebase/merge/force-update branches for PRs without messing anyone else up. In case anyone was wondering :-)

epoberezkin commented 7 years ago

The advantage of using branches though is that other contributors can add their own commits to the branches during the discussion, and it's much easier than to the fork, and you can still use github UI to review/merge. To avoid branch name collision simple guidelines for branch names is usually sufficient (e.g. <username>/<type>/<description>, where type follows semantic commits approach and description is a short lowercase dash-separated phrase).

And you can still have several protected branches (master, next-release) where a smaller number of people can commit/merge.

epoberezkin commented 7 years ago

@handrews just to confirm no objection here to changing id with $id :). I am kind of neutral re other issues, whether to add them now or to postpone. I'd only like to have draft-6 soon (this year?), have it backwards compatible with 4 and to agree on the process (e.g. I very much like to have I-D and not the website as the source of truth. The fact that website has now copy of I-D rather than the link to I-D is damaging its credibility, rather than helping, in my opinion).

awwright commented 7 years ago

@epoberezkin The I-D should definitely be a document that is ready-to-implement.

The website has always had the HTML copy of the draft (xml2rfc produces slightly cleaner HTML than the IETF does... for the most part, I think it butchered some of the examples). Check out https://github.com/json-schema-org/json-schema-org.github.io/issues/10 for an issue related to changing that, though.

epoberezkin commented 7 years ago

https://github.com/json-schema-org/json-schema-org.github.io/issues/10#issuecomment-264110927

handrews commented 7 years ago

I'm officially declaring this issue a dead horse. It's more like an email thread than an issue and has been for a while.

See #176 for further discussion of the most relevant bits and a central point for specific issues.

Relequestual commented 7 years ago

Great, thanks @handrews for referencing the new organisational issue. The fact we need a contributors guide is logged and noted. It will be worked on. We shall seek feedback on it via a PR.