Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding a design proposal template and README. #1838

Merged
merged 10 commits into from
Apr 1, 2019
27 changes: 27 additions & 0 deletions docs/design_proposals/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Design Proposals process

Hello Contributors!

This document describes the process for proposing a new feature or making any
big code changes to `skaffold`.

Having a proposal, will likely reduce the back and forth between the contributor
and the core team. It also makes sure, each new feature or a big change has a
design review.

For any new feature, config or big changes, please add a design proposal document
as described in [Design Proposal Template](./design-proposal-template.md).

Once you create a PR with the proposal, someone from the core team will be
assigned as a design shepherd. The role of the design shepherd will be to make
sure,

1. The feature/change is within Skaffold Philosophy and not a one off
solution for a specific use case.
2. The feature/change scope is well defined.
3. When changing any existing feature, the implementation plan adheres to
[skaffold deprecation policy](./../../deprecation-policy.md)

Once the proposal is in a reasonale shape, we can discuss it in Skaffold bi-weekly
meeting to address any open concerns, and reach to a decision i.e. accept or
punt.
84 changes: 84 additions & 0 deletions docs/design_proposals/design-proposal-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Title

* Author(s): \<your name\>
* Design Shepherd: \<skaffold-core-team-member\>

If you are already working with someone mention their name.
If not, please leave this empty, it will be assigned to a core team member.
* Date: \<date\>
* Status: [Draft/Reviewed/Complete]

## Background

In this section, please mention and describe the new feature, re-design
or re-factor.

Please provide an rationale covering following points:

1. Why is this required?
2. If its re-design, What are cons with current implementation?
3. Is there any another work-around and if yes, why not keep using it.
4. Mention related issues, if there are any.****

Here is an example snippet for a new feature:

___
Currently, skaffold config supports `artifact.sync` as a way to sync files
directly to pods. So far, artifact sync requires a specification of sync
patterns like

```yaml
sync:
'*.js': app/
```

This is error prone and unnecessarily hard to use, because the destination is
already contained in the Dockerfile for docker build. (see #1166, #1581).
In addition, the syncing needs to handle special cases for globbing and often
requires a long list of sync patterns (#1807)
___

## Design

Please describe your solution. Please list any:

* new config changes
* interface changes
* design assumptions

For a new config change, please mention:

* If its a backward compatible config change ?
* If the answer to above question is yes, what would be the deprecation policy?
See [deprecation-policy](./../../deprecation-policy.md#how-do-we-deprecate-things)
requirements.

### Open Issues/Question

Please list any open questions here in the format.

**\<Question\>**

Resolution: Please list the resolution if resolved during the design process or
specify __Not Yet Resolved__

## Implementation plan
We have identified, huge PRs go unnoticed for a long time. Small incremental
changes get reviewed faster and also easier for reviewers.

For a design feature, list a summary of tasks breakdown for e.g.:
For the example desing proposal to infer artifact sync, some of the smaller task
could be:
___

1. Add new config key `infer` to `artifact.sync` and test schema validation.
2. Add inference logic for docker and examples.
3. Support both `infer` and user defined map with precedence rules implemented.
4. Finally, support builder plugins to add sync patterns.

___


## Integration test plan

Please describe what new test cases are you going to consider.