From cffe60d1fc0a8996aa337b357ccbb94ab4429add Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Debois?= Date: Mon, 21 Mar 2016 23:29:29 +0100 Subject: [PATCH] Separate contributions page --- CONTRIBUTING.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 39 +++-------------- 2 files changed, 114 insertions(+), 34 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7fd24ee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Contributing + +Please do! You could add documentation, fix bugs, add to the demos/integrate +with other elm-libraries, or add components. There are opportunities for +both newcomers and experienced Elm programmers: adding documentation, fixing +bugs and adding missing features is a good way to get deeper into the language; +for experienced programmers, every step of the way (so far) has for me been +a surprisingly subtle and complex challenge in finding proper APIs. + +## Adding documentation + +This is perhaps the easiest place to start. In some cases, documentation can be +based more or less directly on the +[MDL documentation](getmdl.io/components). In other cases, you'll need to read +the code needing documentation. If you are new to Elm, this could be a good way +to get deeper into the language. + + - The + [Snackbar](https://github.com/debois/elm-mdl/blob/master/src/Material/Snackbar.elm) + is functional but has no documentation. + ([Issue](https://github.com/debois/elm-mdl/issues/9).) + + - Demo pages need intro text a la MDL docs. + ([Issue](https://github.com/debois/elm-mdl/issues/8).) + +See the [documentation issue +list](https://github.com/debois/elm-mdl/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Adocumentation+) + +## Enhancing/fixing existing components + +Some components are stable but not fully featured. Adding minor features could be a +good way to get started. + +See the [enhancement issue +list](https://github.com/debois/elm-mdl/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Aenhancement). + +## Improving demos / Integration with other libraries + +If you have some experience with other Elm packages, it'd be very interesting to see +if the library interacts properly with these. Right now, + + - The + [Snackbar](https://github.com/debois/elm-mdl/blob/master/src/Material/Snackbar.elm) + could do with more animation, and it'd be very interesting to see if the library + interacts reasonably with elm-html-animation. + ([Issue](https://github.com/debois/elm-mdl/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Ademo).) + + - The main tabs should be connected to a router, so that the url reflects the current tab. + ([Issue](https://github.com/debois/elm-mdl/issues/7).) + +See the [demo issue list](https://github.com/debois/elm-mdl/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Ademo). + +## Contributing components + +The easiest place to start is to add more CSS-only components. These +require no porting of Javascript, just putting together css-classes as +instructed by the +[MDL Component Documentation](https://www.getmdl.io/components/index.html). +These components invariably require serious thinking about what is an +appropriate Elm API and so are usually interesting in their own right for +that reason. Take a look at + + - [Badges](https://www.getmdl.io/components/index.html#badges-section) [Work-in-progress: [Håkon Rossebø](https://github.com/hakonrossebo])] + - [Cards](https://www.getmdl.io/components/index.html#cards-section) + - [Dialogs](https://www.getmdl.io/components/index.html#dialog-section) + - [Footers](https://www.getmdl.io/components/index.html#layout-section/footer) + - [Lists](https://www.getmdl.io/components/index.html#lists-section) + - [Shadows](https://github.com/google/material-design-lite/tree/v1.1.2/src/shadow) + +Progress bars are pure CSS, and spinners seem to use Javascript only to insert +auxiliary DOM-nodes on initialisation. + + - [Loading](https://www.getmdl.io/components/index.html#loading-section) + +The remaining components, use Javascript +in various ways. Toggles seem to use Javascript exclusively to insert ripple-animations and __might__ be easy to implement using the `Ripple.elm` +component: + + - [Toggles](https://www.getmdl.io/components/index.html#toggles-section) + +The rest I haven't looked at; they may or may not be straightforward to port +to Elm. + + - [Tables](https://www.getmdl.io/components/index.html#tables-section) + - [Sliders](https://www.getmdl.io/components/index.html#sliders-section) + - [Menus](https://www.getmdl.io/components/index.html#menus-section) + - [Snackbars](https://www.getmdl.io/components/index.html#snackbar-section) [Work-in-progress] + - [Tooltips](https://www.getmdl.io/components/index.html#tooltips-section) + +### Getting started with a new component + +Each component has its actual code in `src/Material/NameOfComponent.elm` and a demo in +`examples/Demo/NameOfComponent.elm`. These are what you need to construct. +To get started quickly, do this: + +1. Clone this repository +2. Copy the file `src/Material/Template.elm` to `src/Material/NameOfYourComponent.elm`. Rename +as appropriate in the file. +3. Copy the file `examples/Demo/Template.elm` to `examples/Demo/NameOfYourComponent.elm`. +Rename as appropriate in the file. +4. In `examples/Demo.elm`, find all the places that mentions `template` or `Template`, +copy those bits, and rename as appropriate. +5. Compile and open `page.html` in a browser. + +The last tab contains your component. Now all you need is code! + +To avoid duplication of work, +[open an issue](https://github.com/debois/elm-mdl/issues/new) and let everybody know +that you are working on a particular component. diff --git a/README.md b/README.md index a29ef78..231e2da 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ MDL is implemented primarily through CSS, with a little bit of Javascript adding and removing CSS classes in response to DOM events. This port re-implements the CSS parts in Elm, but relies on the CSS of MDL verbatim. -*CAUTION*! This is an early and incomplete prototype. Use at your own risk. +**CAUTION**! This is an early and incomplete prototype. Use at your own risk. ### Get Started @@ -23,12 +23,6 @@ Build the demo: This will construct a file `index.html`; open that in your browser. -The library has a tiny native component (for measuring geometry of rendered - elements, a necessity for re-implementing MDL ripple-animations), and so - cannot be in the elm-package library. If you wish to use the library, I - know no better way than to copy `Material.elm` and `Material/*` to your - own project. - ### Embedding in your own HTML. Initial page load of the demo will produce a flicker, which can only be @@ -45,31 +39,8 @@ browser; this file will set up MDL css and load `elm.js`. ### Contribute -Please do! The easiest place to start is to add more CSS-only components. These require no porting of Javascript, just putting together css-classes as instructed by the [MDL Component Documentation](https://www.getmdl.io/components/index.html). Take a look at +Contributions are warmly encouraged! Whether you are a newcomer to Elm or +an accomplished expert, the MDL port presents interesting challenges. Refer +to [this page](https://github.com/debois/elm-mdl/blob/master/CONTRIBUTING.md) +for a detailed list of possible contributions. - - [Badges](https://www.getmdl.io/components/index.html#badges-section) [Work-in-progress: [Håkon Rossebø](https://github.com/hakonrossebo])] - - [Cards](https://www.getmdl.io/components/index.html#cards-section) - - [Dialogs](https://www.getmdl.io/components/index.html#dialog-section) - - [Footers](https://www.getmdl.io/components/index.html#layout-section/footer) - - [Lists](https://www.getmdl.io/components/index.html#lists-section) - - [Shadows](https://github.com/google/material-design-lite/tree/v1.1.2/src/shadow) - -Progress bars are pure CSS, and spinners seem to use Javascript only to insert -auxiliary DOM-nodes on initialisation. - - - [Loading](https://www.getmdl.io/components/index.html#loading-section) - -The remaining components, use Javascript -in various ways. Toggles seem to use Javascript exclusively to insert ripple-animations and __might__ be easy to implement using the `Ripple.elm` -component: - - - [Toggles](https://www.getmdl.io/components/index.html#toggles-section) - -The rest I haven't looked at; they may or may not be straightforward to port -to Elm. - - - [Tables](https://www.getmdl.io/components/index.html#tables-section) - - [Sliders](https://www.getmdl.io/components/index.html#sliders-section) - - [Menus](https://www.getmdl.io/components/index.html#menus-section) - - [Snackbars](https://www.getmdl.io/components/index.html#snackbar-section) [Work-in-progress] - - [Tooltips](https://www.getmdl.io/components/index.html#tooltips-section)