diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6662073a..1f9baeb8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,7 @@ are very busy and read the mailing lists. This is a rough outline of what a contributor's workflow looks like: +- Create a proposal (if neccessary - see below) and get an LGTM by someone in [maintainer](MAINTAINERS) - Create a topic branch from where you want to base your work (usually master). - Make commits of logical units. - Make sure your commit messages are in the proper format (see below). @@ -40,6 +41,18 @@ This is a rough outline of what a contributor's workflow looks like: Thanks for your contributions! +## Proposals + +For very simple contributions - bug fixes, documentation tweaks, small optimizations, etc. - a proposal is not neccesary. Otherwise, it's necessary to discuss your proposal with other members of the community and get approval from the maintainers. + +To create a proposal, copy the markdown from the [proposal template](PROPOSAL_TEMPLATE.md) and put it in the relevant issue. Once you've gotten an LGTM from a [maintainer](MAINTAINERS), you can proceed with putting together a PR. + +Don't worry if you're proposal is not accepted right away; you'll probably need to make some changes, depending on the scope of the proposal. + +Here's a link which creates a new issue populated with the proposal link: + +[Create a Proposal](https://github.com/coreos/dex/issues/new?body=Proposal%0A%3D%3D%3D%0A%0A%28Feel%20free%20to%20change%20headings%20here%2C%20remove%20sections%20that%20are%20not%20relevant%2C%20or%20add%20other%20sections%29%0A%0A%23%23%20Background%0A%0ADescribe%20what%20problem%20is%20being%20solved%20here%2C%20and%20%28briefly%29%20how%20this%20proposal%20solves%20it.%0A%0A%23%23%20Data%20Model%0A%0ADescribe%20the%20logical%20data%20model%20that%20your%20proposal%20adds.%0A%0A%23%23%20Data%20Storage%0A%0ADescribe%20how%20the%20data%20will%20be%20persisted.%0A%0A%23%23%20API%0A%0ADescribe%20the%20methods%20that%20the%20API%20will%20expose.%20If%20there%20are%20any%20breaking%20changes%20be%20sure%20to%20call%20them%20out%20here.%0A%0A%23%23%20UI/UX%0A%0AIs%20there%20a%20front-end%20component%20to%20this%20work%3F%0A%0A%23%23%20Implementation%0A%0AHere%20is%20where%20you%20can%20go%20into%20detail%20about%20implementation%20details%20like%20data%20structures%2C%20algorithms%2C%20etc.%0A%0A%23%23%20Security%0A%0AWhat%20are%20the%20security%20implications%20of%20this%20proposal%3F%20How%20are%20API%20requests%20authenticated%3F%20Who%20can%20make%20API%20calls%3F%0A%0A%23%23%20OIDC/OAUTH2%0A%0ADoes%20this%20feature%20relate%20to%20any%20spec%3F%20%0A%0A%23%23%20Risks/Alternatives%20Considered%0A%0AWhat%20are%20the%20downsides%20to%20this%20implementation%3F%20What%20other%20alternatives%20were%20considered%3F%0A%0A%23%23%20References%0A%0AIf%20there%27s%20any%20references%20or%20prior%20art%2C%20put%20that%20here.) + ### Format of the Commit Message We follow a rough convention for commit messages that is designed to answer two diff --git a/PROPOSAL_TEMPLATE.md b/PROPOSAL_TEMPLATE.md new file mode 100644 index 00000000..028cd46f --- /dev/null +++ b/PROPOSAL_TEMPLATE.md @@ -0,0 +1,44 @@ +Proposal +=== + +(Feel free to change headings here, remove sections that are not relevant, or add other sections) + +## Background + +Describe what problem is being solved here, and (briefly) how this proposal solves it. + +## Data Model + +Describe the logical data model that your proposal adds. + +## Data Storage + +Describe how the data will be persisted. + +## API + +Describe the methods that the API will expose. If there are any breaking changes be sure to call them out here. + +## UI/UX + +Is there a front-end component to this work? + +## Implementation + +Here is where you can go into detail about implementation details like data structures, algorithms, etc. + +## Security + +What are the security implications of this proposal? How are API requests authenticated? Who can make API calls? + +## OIDC/OAUTH2 + +Does this feature relate to any spec? + +## Risks/Alternatives Considered + +What are the downsides to this implementation? What other alternatives were considered? + +## References + +If there's any references or prior art, put that here. diff --git a/proposal_link b/proposal_link new file mode 100755 index 00000000..cab9a920 --- /dev/null +++ b/proposal_link @@ -0,0 +1,7 @@ +#!/bin/bash -e + +# This creates a URL which will pre-populate an issue with the contents of PROPOSAL_TEMPLATE.md + +BODY=$(python -c "import urllib, sys; print urllib.quote(sys.stdin.read()[0:-1])" < PROPOSAL_TEMPLATE.md) + +echo "https://github.com/coreos/dex/issues/new?body=$BODY"