You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

136 lines
5.3 KiB

  1. # Contributing
  2. ## Introduction
  3. There are a variety of ways to contribute to the development of Semantic. We are a very new project and are looking for an enthusiastic and like-minded group of core contributors. We use the lovely free project management software [Trello](https://trello.com/jack148/recommend) for keeping track of project issues and updates.
  4. Some Trello boards are open publicly, others are limited to contributors. Anyone can share ideas for the direction of the project using our public boards.
  5. If you are looking to be added to contributor board on Semantic and are active in development, please reach out to me by e-mail [jack@myfav.es](mailto:jack@myfav.es)
  6. ### Publicity
  7. One of the easiest ways to support Semantic UI is to get the word out
  8. ## Making Semantic Better
  9. ### Bugs & Issues
  10. Please submit any bugs you encounter when using the library to our [Github Issues Tracker](https://github.com/jlukic/Semantic-UI/issues?state=open).
  11. When submiting a bug report, please include a set of steps to reproduce the issue and any related information, browser, OS etc. If we can't see the issue then it will make solving things much more difficult.
  12. ### Style Guide
  13. Contributors should read over the coding guidelines for the project. Most importantly, the guide for language, as it is one of the most important parts about Semantic UI.
  14. [Language](http://semantic-ui.com/guide/styleguide.html)
  15. [CSS](http://semantic-ui.com/guide/cssguide.html)
  16. [Javascript](http://semantic-ui.com/guide/javascriptguide.html)
  17. ### Pull Requests
  18. Anyone can jump on the issues board and grab off bugs to fix. This is probably the best way to become a contributor to Semantic. Be sure to adhere to the style guides when submitting code.
  19. * [Create a Pull Request](https://github.com/jlukic/Semantic-UI/compare/)
  20. * [View Open Issues](https://github.com/jlukic/Semantic-UI/issues?state=open)
  21. ### Expanding UI
  22. Semantic is looking for people to help contribute new core UI components, and suggest extensions for the library.
  23. If you have suggestions for components missing from Semantic which you'd like to see in future versions please add them to our public UI Component board. The current list of upcoming components, and their current development status can be seen on the contributor UI board.
  24. #### Visit UI Development Boards
  25. [Public](https://trello.com/b/Q8uTLy2T) |
  26. [Contributor](https://trello.com/b/yVsh5Rds)
  27. ## Specification Development
  28. We're looking currently for ideas on the best way to expand Semantic to include both core library and third party components. This requires creating a component specification which can be used by anyone to create ui components, and a package management system (website or command line) for authors to distribute them.
  29. These features are very important for the healthy growth of the Semantic ecosystem, and to expand the number of components available to users.
  30. #### Visit Community Development Boards
  31. [Public](https://trello.com/b/FZvMsVIM) |
  32. [Contributor](https://trello.com/b/eOoZwNBQ)
  33. ---
  34. ## Development
  35. A guide to developing locally
  36. ## Running Locally
  37. It may be useful to run the development docs locally when working on a forked version of semantic, as the docs themselves help in testing out changes to ui components.
  38. ### 1) Install Node
  39. Semantic docs are written in DocPad which requires NodeJS.
  40. Make sure npm does not require sudo to operate, this might cause permissions issues.
  41. * [Node JS via Package Manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager)
  42. * [Installing Node JS without sudo](https://gist.github.com/isaacs/579814)
  43. ### 2) Install Dependencies
  44. ```bash
  45. npm install -g docpad
  46. ```
  47. ```bash
  48. npm install -g grunt-cli
  49. ```
  50. ### 3) Fork Semantic
  51. [Fork](https://github.com/jlukic/Semantic-UI/fork)
  52. ### 4) Start Your Server
  53. It's important to note that all server code exists inside of `/node` in the project. So all commands should be run relative to that directory.
  54. ```bash
  55. cd node
  56. docpad run
  57. ```
  58. Docpad should now run an instance of semantic-ui.com locally you can access at `http://localhost:9778`
  59. ## Fixing Bugs
  60. ### Watch Script
  61. If you are working on fixing a UI component that is part of Semantic, your best bet is to work actively on the file in `/src/{type}/{elementname}/` while running a watch script from grunt. This will rebuild the docs after you make changes, so you can see if you have corrected the issue you are fixing.
  62. To see exactly what this is doing you can check out our [commented gruntfile](https://github.com/jlukic/Semantic-UI/blob/master/node/Gruntfile.js)
  63. ```bash
  64. grunt
  65. ```
  66. The watch task is the default grunt task for Semantic, so you can start it quite simply.
  67. ### Packaging Elements
  68. For convenience there is also a separate grunt command for building minified, packaged, and compressed versions of the library.
  69. ```bash
  70. grunt build
  71. ```
  72. ## The Future
  73. ### UI Dev Kits
  74. We are working to create development kits for writing and distributing third party UI definitions. These, are planned to land after our 1.0 release and allow other developers to contribute ui components or reskins of existing components.
  75. For more information on the development of the UI specification for third party components, please visit our community discussion boards on Trello
  76. #### Development Boards
  77. [Public](https://trello.com/b/FZvMsVIM) |
  78. [Contributor](https://trello.com/b/eOoZwNBQ)