From 74eccdb4457cd5eece35c890be7c3cc6d446481d Mon Sep 17 00:00:00 2001
From: Gunnar Wagenknecht <gunnar@wagenknecht.org>
Date: Wed, 4 Apr 2018 11:18:15 +0200
Subject: [PATCH] Add Contribution Guide and other supporting doc
Signed-off-by: Gunnar Wagenknecht <gunnar@wagenknecht.org>
---
.github/ISSUE_TEMPLATE.md | 24 +++++++++++
.github/PULL_REQUEST_TEMPLATE.md | 37 +++++++++++++++++
.gitignore | 3 ++
CONTRIBUTING.md | 70 ++++++++++++++++++++++++++++++++
README.adoc | 38 +++--------------
package.json | 10 +++--
6 files changed, 145 insertions(+), 37 deletions(-)
create mode 100644 .github/ISSUE_TEMPLATE.md
create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
create mode 100644 CONTRIBUTING.md
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 0000000..96129d2
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,24 @@
+<!--
+Issue template
+To Use this Template:
+* Fill out what you can
+* Delete what you do not fill out
+-->
+
+NOTE: ISSUES ARE NOT FOR HELP - Ask for Help at incubation@eclipse.org
+
+#### Issue/Problem Description
+* Describe the problem you are facing.
+
+#### Proposal
+* Please describe proposed solution here (if you already have on in mind).
+
+#### Proposal Benefits
+* What do we gain by incorporatin the proposal?
+
+#### Challenges
+* What are the drawbacks of the proposed changes?
+
+#### References
+* Add links to existing discussions, issues, etc.
+
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..12252da
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,37 @@
+# Pull Request template
+
+Please, go through these steps before you submit a PR.
+
+1. Make sure that:
+ 1. You have done your changes in a separate branch. Branches MUST have descriptive names that start with either the `fix/` or `feature/` prefixes. Good examples are: `fix/signin-issue` or `feature/issue-templates`.
+ 2. You have a descriptive commit message with a short title (first line).
+ 3. `npm test` doesn't throw any error. If it does, fix them first and amend your commit (`git commit --amend`).
+ 4. All your commits are signed (`git commit -s`).
+ 5. There are no merge commits in your branch (use Git Rebase instead).
+
+2. After these steps, you're ready to open a pull request.
+ 1. Your pull request MUST NOT target the `master` branch on this repository. You probably want to target `develop` instead.
+ 2. Give a descriptive title to your PR, reference any existing issues and discussions.
+ 3. Provide a description of your changes.
+ 4. Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes (if such).
+
+IMPORTANT: Please review the [CONTRIBUTING.md](../CONTRIBUTING.md) file for detailed contributing guidelines.
+
+## PLEASE REMOVE THIS TEMPLATE BEFORE SUBMITTING
+
+#### Problem Description
+* Describe the problem this PR is addressing.
+* Reference any existing issues.
+
+#### Proposed Changes
+* Please summarize the proposed changes here
+
+#### Benefits
+* What are the gains by incorporatin the changes?
+
+#### Challenges
+* What are the drawbacks of the proposed changes?
+* Are there any other consequences/implications?
+
+#### References
+* Add links to existing discussions, issues, etc.
diff --git a/.gitignore b/.gitignore
index 14d62b1..8af51c6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,3 +59,6 @@ typings/
# npm package-lock.json
package-lock.json
+
+# for now ignore any generated html
+.html
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..8bdea84
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,70 @@
+# Eclipse Development Process Community Contributing Guide
+
+This directory contains the source for the [Eclipse Development Process](eclipse_development_process.adoc) in AsciiDoc format, the build script, and generated output.
+The build script is configured to generate output for a specific version of the document and running the build (`npm run build`) may overwrite any existing document.
+
+The output files (eg., `*.html`) may be live documents that may be included by other documents found in the repository and also externally, so take care with what you commit.
+
+## Installing NPM
+
+NPM is required for generating the output files.
+Please have a look at [Get npm!](https://www.npmjs.com/get-npm)
+
+## Installing Asciidoctor
+
+Please allow NPM to install all dependencies by running `npm run install`.
+
+## AsciiDoc Syntax
+
+Please refere to [AsciiDoc Syntax Quick Reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/).
+
+## Making changes
+
+Follow [AsciiDoc Recommended Practices](https://asciidoctor.org/docs/asciidoc-recommended-practices/) when making changes.
+In particular, the one sentence per line recommendation is important to us.
+This makes it much easier to view the diffs in git.
+
+As a sanity check, `npm test` should be run before committing.
+It should be run automatically because npm install should setup Git a pre-coomit hook automatically.
+
+Sometimes, it isn’t possible to fix all lint issue, e.g., because you’d like to try out something for testing or discussion.
+In that case, you can use `git commit --no-verify` to temporarily bypass the check.
+
+## Update Process
+
+Please submit pull requests for any changes.
+We’ll use pull requests for discussing them.
+
+New requirements, ideas and significant changed should be captured in issues.
+Larger items should be brought to the Architecture Council mailing list for discussion.
+Discussion summary/results must be documented (and referenced) in pull requests and issues.
+
+**No pull request** can be merged **without being reviewed**.
+
+### Sign-off Process
+
+All commits to code in the Eclipse organization **MUST** be signed off. This is done when committing from git passing the extra argument `-s` e.g.:
+
+```shell
+git commit -s -m "Improve the EDP"
+```
+
+For more info on contributing via Git, see [here](http://wiki.eclipse.org/Development_Resources/Contributing_via_Git).
+
+### Small Changes
+
+Changes less than 10 lines or so (e.g.: correcting typos, small changes to `README.adoc` and such-like) can be made directly on a branch.
+
+Any change to `eclipse_development_process.adoc` and its related documents is **NEVER** considered a simple change. It requires a pull request and full EMO review and approval before merge.
+
+## Branching Model
+
+This repository uses two branches: `master` and `develop`.
+
+`master` is the reviewed and approved *"current"* version of the Eclipse Development Process documents.
+
+`develop` contains changes that are in progress (*"under development"*) and may not be *ready for production*, this is reviewed and approved by EMO and the Eclipse Foundation Board of Directors.
+
+From the `develop` branch, you create *topic* branches to work on individual features and fixes. Once your feature/fix is ready to go, you request a merge into `develop` by opening a pull request.
+
+Once develop is in a ready *"to be released"* state, we’ll create tag and a pull request to `master`. The pull request will be merged once all necessary reviews and approvals are in.
diff --git a/README.adoc b/README.adoc
index 0fbac82..902e1bb 100644
--- a/README.adoc
+++ b/README.adoc
@@ -25,38 +25,10 @@ Please submit feedback using one of the following ways:
== Contributing
-This directory contains the source for the[Eclipse Development Process](eclipse_development_process.adoc) in AsciiDoc format, the build script, and generated output.
-The build script is configured to generate output for a specific version of the document and running the build (`npm run build`) may overwrite any existing document.
+IMPORTANT: Any changes to `eclipse_development_process.adoc` and its accompanying documents (even trivial one, eg. correcting typos) require a pull request and full EMO review and approval before merge.
-The output files (eg., `*.html`) may be live documents that may be included by other documents found in the repository and also externally, so take care with what you commit.
+. Fork/clone the repository
+. Create a new branch based of `develop`
+. Run `npm install`
+. Read the link:CONTRIBUTING.md[Contribution Guide]
-=== Installing NPM
-NPM is required for generating the output files.
-Please have a look at link:https://www.npmjs.com/get-npm[Get npm!]
-
-=== Installing Asciidoctor
-Please allow NPM to install all dependencies by running `npm run install`.
-
-=== AsciiDoc Syntax
-Please refere to link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference].
-
-=== Making changes
-Follow link:https://asciidoctor.org/docs/asciidoc-recommended-practices/[AsciiDoc Recommended Practices] when making changes.
-In particular, the one sentence per line recommendation is important to us.
-This makes it much easier to view the diffs in git.
-
-As a sanity check, `npm run lint` should be run before committing.
-It should be run automatically because npm install should setup Git a pre-coomit hook automatically.
-
-TIP: Sometimes, it isn’t possible to fix all lint issue, e.g., because you’d like to try out something for testing or discussion.
-In that case, you can use `git commit --no-verify` to temporarily bypass the check.
-
-=== Update Process
-Please submit pull requests for any proposals/semantic changes/enhancements.
-We’ll use pull requests for discussing them.
-
-Requirements, ideas and todos should be captured in issues and should be referenced in pull requests addressing them.
-
-A note for committers: spelling, grammatical as well as cosmetic corrections don’t require a pull request *except* for the official [Eclipse Development Process document](eclipse_development_process.adoc).
-
-_Any change to `eclipse_development_process.adoc` requires a pull request and full EMO review and approval before merge._
diff --git a/package.json b/package.json
index d12ddf4..8cc9e6f 100644
--- a/package.json
+++ b/package.json
@@ -17,10 +17,12 @@
"textlint-rule-write-good": "^1.6.2"
},
"scripts": {
- "lint": "textlint -f pretty-error *.adoc",
- "lint:fix": "textlint --fix *.adoc",
- "build": "asciidoctorjs --help",
- "precommit": "npm run lint"
+ "lint": "textlint -f pretty-error README.adoc *.md",
+ "lint:edp": "textlint -f pretty-error eclipse_*.adoc",
+ "lint:fix": "textlint --fix README.adoc *.md",
+ "build": "asciidoctorjs eclipse_development_process.adoc",
+ "precommit": "npm test",
+ "test": "npm run lint"
},
"repository": {
"type": "git",
--
GitLab