1 |
|
2 |
|
3 | <h1>Projectz</h1>
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 | <span class="badge-travisci"><a href="http://travis-ci.com/bevry/projectz" title="Check this project's build status on TravisCI"><img src="https://img.shields.io/travis/com/bevry/projectz/master.svg" alt="Travis CI Build Status" /></a></span>
|
11 | <span class="badge-npmversion"><a href="https://npmjs.org/package/projectz" title="View this project on NPM"><img src="https://img.shields.io/npm/v/projectz.svg" alt="NPM version" /></a></span>
|
12 | <span class="badge-npmdownloads"><a href="https://npmjs.org/package/projectz" title="View this project on NPM"><img src="https://img.shields.io/npm/dm/projectz.svg" alt="NPM downloads" /></a></span>
|
13 | <span class="badge-daviddm"><a href="https://david-dm.org/bevry/projectz" title="View the status of this project's dependencies on DavidDM"><img src="https://img.shields.io/david/bevry/projectz.svg" alt="Dependency Status" /></a></span>
|
14 | <span class="badge-daviddmdev"><a href="https://david-dm.org/bevry/projectz#info=devDependencies" title="View the status of this project's development dependencies on DavidDM"><img src="https://img.shields.io/david/dev/bevry/projectz.svg" alt="Dev Dependency Status" /></a></span>
|
15 | <br class="badge-separator" />
|
16 | <span class="badge-githubsponsors"><a href="https://github.com/sponsors/balupton" title="Donate to this project using GitHub Sponsors"><img src="https://img.shields.io/badge/github-donate-yellow.svg" alt="GitHub Sponsors donate button" /></a></span>
|
17 | <span class="badge-patreon"><a href="https://patreon.com/bevry" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>
|
18 | <span class="badge-flattr"><a href="https://flattr.com/profile/balupton" title="Donate to this project using Flattr"><img src="https://img.shields.io/badge/flattr-donate-yellow.svg" alt="Flattr donate button" /></a></span>
|
19 | <span class="badge-liberapay"><a href="https://liberapay.com/bevry" title="Donate to this project using Liberapay"><img src="https://img.shields.io/badge/liberapay-donate-yellow.svg" alt="Liberapay donate button" /></a></span>
|
20 | <span class="badge-buymeacoffee"><a href="https://buymeacoffee.com/balupton" title="Donate to this project using Buy Me A Coffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg" alt="Buy Me A Coffee donate button" /></a></span>
|
21 | <span class="badge-opencollective"><a href="https://opencollective.com/bevry" title="Donate to this project using Open Collective"><img src="https://img.shields.io/badge/open%20collective-donate-yellow.svg" alt="Open Collective donate button" /></a></span>
|
22 | <span class="badge-crypto"><a href="https://bevry.me/crypto" title="Donate to this project using Cryptocurrency"><img src="https://img.shields.io/badge/crypto-donate-yellow.svg" alt="crypto donate button" /></a></span>
|
23 | <span class="badge-paypal"><a href="https://bevry.me/paypal" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
|
24 | <span class="badge-wishlist"><a href="https://bevry.me/wishlist" title="Buy an item on our wishlist for us"><img src="https://img.shields.io/badge/wishlist-donate-yellow.svg" alt="Wishlist browse button" /></a></span>
|
25 |
|
26 |
|
27 |
|
28 |
|
29 |
|
30 |
|
31 | Stop wasting time syncing and updating your project's README and Package Files!
|
32 |
|
33 |
|
34 |
|
35 |
|
36 | This far, projectz is used directly by [802 repositories](https://github.com/bevry/projectz/network/dependents) and [348 packages](https://github.com/bevry/projectz/network/dependents?dependent_type=PACKAGE), and indirectly by [2936 repositories](https://libraries.io/npm/projectz/dependent-repositories) and [349 packages](https://libraries.io/npm/projectz/dependents).
|
37 |
|
38 | [Watch the talk.](https://youtu.be/IAB8_UlcNWI)
|
39 |
|
40 | Here's some of the things it can do:
|
41 |
|
42 | - [Keep your projects data files synchronised appropriately](https://github.com/bevry/projectz#data-files), supports:
|
43 | - `package.json`
|
44 | - `bower.json`
|
45 | - `component.json`
|
46 | - `jquery.json`
|
47 | - [Create beautiful standardised readme files that stay in sync with your data files](https://github.com/bevry/projectz#readme-files), supports:
|
48 | - `README`
|
49 | - `CONTRIBUTING`
|
50 | - `LICENSE`
|
51 | - `BACKERS`
|
52 | - `HISTORY`
|
53 | - Automatic injection of the appropriate installation methods, supports:
|
54 | - [npm](https://www.npmjs.com)
|
55 | - [jspm](http://jspm.io)
|
56 | - [Component](http://github.com/component/component)
|
57 | - [Bower](http://bower.io/)
|
58 | - [Editions](https://github.com/bevry/editions)
|
59 | - [DocPad](https://docpad.org) Plugins
|
60 | - Automatic injection of your desired [badges](https://github.com/bevry/badges)
|
61 | - Automatic injection of your [SPDX](http://spdx.org/licenses/) license information
|
62 | - Keep your data and readme files up to date with remote data, supports:
|
63 | - Pulling in your latest contributors from GitHub
|
64 | - Pulling in your latest sponsors from remote APIs ([coming soon](https://github.com/bevry/projectz/issues/80))
|
65 |
|
66 |
|
67 |
|
68 | <h2>Install</h2>
|
69 |
|
70 | <a href="https://npmjs.com" title="npm is a package manager for javascript"><h3>npm</h3></a>
|
71 | <h4>Install Globally</h4>
|
72 | <ul>
|
73 | <li>Install: <code>npm install --global projectz</code></li>
|
74 | <li>Executable: <code>projectz</code></li>
|
75 | </ul>
|
76 | <h4>Install Locally</h4>
|
77 | <ul>
|
78 | <li>Install: <code>npm install --save projectz</code></li>
|
79 | <li>Executable: <code>npx projectz</code></li>
|
80 | <li>Import: <code>import * as pkg from ('projectz')</code></li>
|
81 | <li>Require: <code>const pkg = require('projectz')</code></li>
|
82 | </ul>
|
83 |
|
84 | <h3><a href="https://editions.bevry.me" title="Editions are the best way to produce and consume packages you care about.">Editions</a></h3>
|
85 |
|
86 | <p>This package is published with the following editions:</p>
|
87 |
|
88 | <ul><li><code>projectz</code> aliases <code>projectz/source/index.js</code></li>
|
89 | <li><code>projectz/source/index.js</code> is <a href="https://en.wikipedia.org/wiki/ECMAScript#ES.Next" title="ECMAScript Next">ESNext</a> source code for <a href="https://nodejs.org" title="Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine">Node.js</a> with <a href="https://nodejs.org/dist/latest-v5.x/docs/api/modules.html" title="Node/CJS Modules">Require</a> for modules</li></ul>
|
90 |
|
91 |
|
92 |
|
93 |
|
94 | ## Running Projectz
|
95 |
|
96 | ### Directly
|
97 |
|
98 | Once installed locally, you can compile your project using projectz by running the following in your terminal:
|
99 |
|
100 | ```shell
|
101 | npx projectz compile
|
102 | ```
|
103 |
|
104 | ### Automatically
|
105 |
|
106 | To make projectz more automatic, we recommended adding the direct command above to your build tool.
|
107 |
|
108 | If you don't use a build tool, but do use npm, then you can add the following to your project's `package.json` file:
|
109 |
|
110 | ```json
|
111 | {
|
112 | "scripts": {
|
113 | "compile": "projectz compile",
|
114 | "posttest": "npm run compile"
|
115 | }
|
116 | }
|
117 | ```
|
118 |
|
119 | The `compile` script here is runnable via the command `npm run-script compile` and will compile your project with projectz.
|
120 |
|
121 | The `posttest` script here automatically compiles your project with projectz after your tests have successfully completed, providing you use `npm test` to run your tests. This is a great place to put projectz as projectz only updates meta documents so won't affect your test, and will always run before a publish.
|
122 |
|
123 | ### GitHub Rate Limiting
|
124 |
|
125 | If you get a rate limit warning, you will need to add `GITHUB_ACCESS_TOKEN` (or a `GITHUB_CLIENT_ID` AND `GITHUB_CLIENT_SECRET` combination) to your environment. To do this:
|
126 |
|
127 | 1. Create a personal access token for your computer at: https://github.com/settings/tokens
|
128 | 2. Projectz needs the readonly/access permissions for repos and users
|
129 | 3. Generate the token and copy it
|
130 | 4. Inside your dotfile profile (`.bashrc`, `.zshrc`) add `export GITHUB_ACCESS_TOKEN="the token value"`
|
131 | 5. Open a new shell, or run `export GITHUB_ACCESS_TOKEN="the token value"` in your current shell
|
132 | 6. Run projectz again
|
133 |
|
134 | ## Configuring Projectz
|
135 |
|
136 | ### Data Files
|
137 |
|
138 | Projectz helps you maintain the following data files:
|
139 |
|
140 | - `package.json`
|
141 | - `bower.json`
|
142 | - `component.json`
|
143 | - `jquery.json`
|
144 |
|
145 | It does this by reading them, combining their data in memory, and then outputting the appropriate fields and over-rides for each file.
|
146 |
|
147 | If you are making use of multiple meta data files, you may find defining a projectz meta file (`projectz.json` for JSON, or `projectz.cson` for [CSON](https://github.com/bevry/cson)) to be useful. The projectz meta file can serve as a central location for the configuration of all the other files. However, if you only require one meta data file, then you can ignore this ability.
|
148 |
|
149 | Projectz takes notes of these meta data fields:
|
150 |
|
151 | ```javascript
|
152 | {
|
153 | // Specify your project's human readable name
|
154 | "title": "Projectz",
|
155 |
|
156 | // Specify your project name
|
157 | "name": "projectz",
|
158 |
|
159 | // Specify your project's Website URL
|
160 | "homepage": "https://github.com/bevry/projectz",
|
161 |
|
162 | // Specify your project's demo URL
|
163 | // If this is missing, and `homepage` is set, we set it to the `homepage` value
|
164 | "demo": "https://github.com/bevry/projectz",
|
165 |
|
166 | // Specify your project description
|
167 | "description": "Stop wasting time syncing and updating your project's README and Package Files!",
|
168 |
|
169 | // Specify your project's SPDX License
|
170 | // Uses https://www.npmjs.com/packages/spdx for parsing
|
171 | "license": "MIT",
|
172 |
|
173 | // Specify your whether the project can run on the client-side in web browsers
|
174 | // If this is missing, and the component or bower package files exist, then this becomes `true`
|
175 | "browsers": true,
|
176 |
|
177 | // Specify your project's author details
|
178 | // Can be an array or CSV string
|
179 | "author": "2013+ Bevry Pty Ltd <us@bevry.me> (http://bevry.me)",
|
180 |
|
181 | // Specify your maintainers
|
182 | "maintainers": [
|
183 | "Benjamin Lupton (b@lupton.cc) (http://balupton.com)"
|
184 | ],
|
185 |
|
186 | // Specify your sponsors
|
187 | "sponsors": [
|
188 | "Benjamin Lupton (b@lupton.cc) (http://balupton.com)"
|
189 | ],
|
190 |
|
191 | // Specify your contributors
|
192 | // This is automatically combined with the contributors from the GitHub Repository API
|
193 | "contributors": [
|
194 | "Benjamin Lupton (b@lupton.cc) (http://balupton.com)"
|
195 | ],
|
196 |
|
197 | // Specify your project's repository details
|
198 | // If this is missing, and `homepage` is a GitHub URL, this determined automatically
|
199 | "repository": {
|
200 | "type": "git",
|
201 | "url": "https://github.com/bevry/projectz.git"
|
202 | },
|
203 |
|
204 | // Specify your project's issue tracker
|
205 | // If this is missing, and `repository` is a GitHub repository, this determined automatically
|
206 | "bugs": {
|
207 | "url": "https://github.com/bevry/projectz/issues"
|
208 | },
|
209 |
|
210 | // Specify your project's badges for use in the readme files
|
211 | // Projectz renders badges by sending the `badges` field to the `badges` package.
|
212 | // Below is some sample projectz configuration for this field to render our most common badges.
|
213 | // Even more badge types and configurations are available than just those included below.
|
214 | // Complete details of what is available can be found over at the badges package:
|
215 | // https://github.com/bevry/badges
|
216 | "badges": {
|
217 | "list": [
|
218 | "travisci",
|
219 | "npmversion",
|
220 | "npmdownloads",
|
221 | "daviddm",
|
222 | "daviddmdev",
|
223 | "---",
|
224 | "slackin",
|
225 | "patreon",
|
226 | "gratipay",
|
227 | "flattr",
|
228 | "paypal",
|
229 | "bitcoin",
|
230 | "wishlist"
|
231 | ],
|
232 | "config": {
|
233 | "patreonUsername": "bevry",
|
234 | "gratipayUsername": "bevry",
|
235 | "flattrUsername": "balupton",
|
236 | "paypalURL": "https://bevry.me/paypal",
|
237 | "bitcoinURL": "https://bevry.me/bitcoin",
|
238 | "wishlistURL": "https://bevry.me/wishlist",
|
239 | "slackinURL": "https://slack.bevry.me"
|
240 | }
|
241 | },
|
242 |
|
243 | // If you are using the projectz meta file, you can also define this field
|
244 | // it allows you to set the configuration for other package systems
|
245 | "packages": {
|
246 | "bower": {},
|
247 | "component": {},
|
248 | "jquery": {}
|
249 | }
|
250 | }
|
251 | ```
|
252 |
|
253 | ### Readme Files
|
254 |
|
255 | Projectz helps you maintain the following readme files:
|
256 |
|
257 | - `README.md`
|
258 | - `CONTRIBUTING.md`
|
259 | - `LICENSE.md`
|
260 | - `BACKERS.md`
|
261 | - `HISTORY.md`
|
262 |
|
263 | It does this by reading them, and replacing comment tags with the appropriate data.
|
264 |
|
265 | The following comment tags are supported:
|
266 |
|
267 | - `<!-- TITLE -->` — outputs the package's `title` field
|
268 | - `<!-- BADGES -->` — outputs the badges you have enabled from your package's `badges` field
|
269 | - `<!-- DESCRIPTION -->` — outputs the package's `description` field
|
270 | - `<!-- INSTALL -->` — outputs the package's installation instructions
|
271 | - `<!-- HISTORY -->` — outputs a link to the `HISTORY` file if it exists, otherwise if it is a Github repository, outputs a link to the releases page
|
272 | - `<!-- CONTRIBUTE -->` — outputs a link to the `CONTRIBUTE` file if it exists
|
273 | - `<!-- BACKERS -->` — outputs who the backers are for the project, including maintainers, sponsors, funding badges, and contributors
|
274 | - `<!-- LICENSE -->` — outputs a summary of the license information
|
275 |
|
276 | As well as these comment tags for updating entire files:
|
277 |
|
278 | - `<!-- LICENSEFILE -->` — outputs the complete license information
|
279 | - `<!-- BACKERSFILE -->` — same as `<!-- BACKERS -->` but made for an individual file instead
|
280 |
|
281 | As an example, here is a a basic `README.md` file:
|
282 |
|
283 | <!-- TITLE -->
|
284 | <!-- BADGES -->
|
285 | <!-- DESCRIPTION -->
|
286 | <!-- INSTALL -->
|
287 |
|
288 | ## Usage
|
289 | Usage instructions go here
|
290 |
|
291 | <!-- HISTORY -->
|
292 | <!-- CONTRIBUTE -->
|
293 | <!-- BACKERS -->
|
294 | <!-- LICENSE -->
|
295 |
|
296 | This README is also, expectedly, built with projectz. [View its source.](https://raw.githubusercontent.com/bevry/projectz/master/README.md)
|
297 |
|
298 |
|
299 |
|
300 | <h2>History</h2>
|
301 |
|
302 | <a href="https://github.com/bevry/projectz/blob/master/HISTORY.md#files">Discover the release history by heading on over to the <code>HISTORY.md</code> file.</a>
|
303 |
|
304 |
|
305 |
|
306 |
|
307 |
|
308 |
|
309 | <h2>Contribute</h2>
|
310 |
|
311 | <a href="https://github.com/bevry/projectz/blob/master/CONTRIBUTING.md#files">Discover how you can contribute by heading on over to the <code>CONTRIBUTING.md</code> file.</a>
|
312 |
|
313 |
|
314 |
|
315 |
|
316 |
|
317 |
|
318 | <h2>Backers</h2>
|
319 |
|
320 | <h3>Maintainers</h3>
|
321 |
|
322 | These amazing people are maintaining this project:
|
323 |
|
324 | <ul><li><a href="http://balupton.com">Benjamin Lupton</a> — <a href="https://github.com/bevry/projectz/commits?author=balupton" title="View the GitHub contributions of Benjamin Lupton on repository bevry/projectz">view contributions</a></li>
|
325 | <li><a href="http://robloach.net">Rob Loach</a> — <a href="https://github.com/bevry/projectz/commits?author=RobLoach" title="View the GitHub contributions of Rob Loach on repository bevry/projectz">view contributions</a></li>
|
326 | <li><a href="http://ghuser.io/jamesgeorge007">James George</a> — <a href="https://github.com/bevry/projectz/commits?author=jamesgeorge007" title="View the GitHub contributions of James George on repository bevry/projectz">view contributions</a></li></ul>
|
327 |
|
328 | <h3>Sponsors</h3>
|
329 |
|
330 | No sponsors yet! Will you be the first?
|
331 |
|
332 | <span class="badge-githubsponsors"><a href="https://github.com/sponsors/balupton" title="Donate to this project using GitHub Sponsors"><img src="https://img.shields.io/badge/github-donate-yellow.svg" alt="GitHub Sponsors donate button" /></a></span>
|
333 | <span class="badge-patreon"><a href="https://patreon.com/bevry" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>
|
334 | <span class="badge-flattr"><a href="https://flattr.com/profile/balupton" title="Donate to this project using Flattr"><img src="https://img.shields.io/badge/flattr-donate-yellow.svg" alt="Flattr donate button" /></a></span>
|
335 | <span class="badge-liberapay"><a href="https://liberapay.com/bevry" title="Donate to this project using Liberapay"><img src="https://img.shields.io/badge/liberapay-donate-yellow.svg" alt="Liberapay donate button" /></a></span>
|
336 | <span class="badge-buymeacoffee"><a href="https://buymeacoffee.com/balupton" title="Donate to this project using Buy Me A Coffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg" alt="Buy Me A Coffee donate button" /></a></span>
|
337 | <span class="badge-opencollective"><a href="https://opencollective.com/bevry" title="Donate to this project using Open Collective"><img src="https://img.shields.io/badge/open%20collective-donate-yellow.svg" alt="Open Collective donate button" /></a></span>
|
338 | <span class="badge-crypto"><a href="https://bevry.me/crypto" title="Donate to this project using Cryptocurrency"><img src="https://img.shields.io/badge/crypto-donate-yellow.svg" alt="crypto donate button" /></a></span>
|
339 | <span class="badge-paypal"><a href="https://bevry.me/paypal" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
|
340 | <span class="badge-wishlist"><a href="https://bevry.me/wishlist" title="Buy an item on our wishlist for us"><img src="https://img.shields.io/badge/wishlist-donate-yellow.svg" alt="Wishlist browse button" /></a></span>
|
341 |
|
342 | <h3>Contributors</h3>
|
343 |
|
344 | These amazing people have contributed code to this project:
|
345 |
|
346 | <ul><li><a href="http://balupton.com">Benjamin Lupton</a> — <a href="https://github.com/bevry/projectz/commits?author=balupton" title="View the GitHub contributions of Benjamin Lupton on repository bevry/projectz">view contributions</a></li>
|
347 | <li><a href="https://github.com/pflannery">Peter Flannery</a> — <a href="https://github.com/bevry/projectz/commits?author=pflannery" title="View the GitHub contributions of Peter Flannery on repository bevry/projectz">view contributions</a></li>
|
348 | <li><a href="http://robloach.net">Rob Loach</a> — <a href="https://github.com/bevry/projectz/commits?author=RobLoach" title="View the GitHub contributions of Rob Loach on repository bevry/projectz">view contributions</a></li>
|
349 | <li><a href="http://ghuser.io/jamesgeorge007">James George</a> — <a href="https://github.com/bevry/projectz/commits?author=jamesgeorge007" title="View the GitHub contributions of James George on repository bevry/projectz">view contributions</a></li>
|
350 | <li><a href="https://github.com/Zearin">Zearin</a> — <a href="https://github.com/bevry/projectz/commits?author=Zearin" title="View the GitHub contributions of Zearin on repository bevry/projectz">view contributions</a></li>
|
351 | <li><a href="https://github.com/vsopvsop">vsopvsop</a> — <a href="https://github.com/bevry/projectz/commits?author=vsopvsop" title="View the GitHub contributions of vsopvsop on repository bevry/projectz">view contributions</a></li>
|
352 | <li><a href="http://zdroid.github.io">Zlatan Vasović</a> — <a href="https://github.com/bevry/projectz/commits?author=zdroid" title="View the GitHub contributions of Zlatan Vasović on repository bevry/projectz">view contributions</a></li>
|
353 | <li><a href="http://www.blizzard.com">Peter Chanthamynavong</a> — <a href="https://github.com/bevry/projectz/commits?author=peterkc" title="View the GitHub contributions of Peter Chanthamynavong on repository bevry/projectz">view contributions</a></li>
|
354 | <li><a href="http://mightyi.am">Shahar Dawn Or</a> — <a href="https://github.com/bevry/projectz/commits?author=mightyiam" title="View the GitHub contributions of Shahar Dawn Or on repository bevry/projectz">view contributions</a></li>
|
355 | <li><a href="http://github.com/apps/dependabot-preview">dependabot-preview[bot]</a> — <a href="https://github.com/bevry/projectz/commits?author=dependabot-preview[bot]" title="View the GitHub contributions of dependabot-preview[bot] on repository bevry/projectz">view contributions</a></li></ul>
|
356 |
|
357 | <a href="https://github.com/bevry/projectz/blob/master/CONTRIBUTING.md#files">Discover how you can contribute by heading on over to the <code>CONTRIBUTING.md</code> file.</a>
|
358 |
|
359 |
|
360 |
|
361 |
|
362 |
|
363 |
|
364 | <h2>License</h2>
|
365 |
|
366 | Unless stated otherwise all works are:
|
367 |
|
368 | <ul><li>Copyright © 2013+ <a href="http://bevry.me">Bevry Pty Ltd</a></li></ul>
|
369 |
|
370 | and licensed under:
|
371 |
|
372 | <ul><li><a href="http://spdx.org/licenses/MIT.html">MIT License</a></li></ul>
|
373 |
|
374 |
|