|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thank you so much for contributing to this project! Our mission is to streamline |
| 4 | +website production. We aim to provide a set of lean developer tools that are easily |
| 5 | +installable, runnable, and usable for either small or big interactive projects. |
| 6 | + |
| 7 | +Fileset doesn't intend to be the next big web static web server. It is meant to |
| 8 | +be a thin alternative to Netlify, and allow existing users of Google Cloud |
| 9 | +Platform to serve static sites to users with just a little bit of extra dynamic |
| 10 | +functionality. |
| 11 | + |
| 12 | +Keep the above in mind when adding features to Fileset. |
| 13 | + |
| 14 | +## Philosophy |
| 15 | + |
| 16 | +- Write as little code as possible, but as much as necessary to complete a task |
| 17 | + correctly. |
| 18 | +- Avoid introducing new dependencies as much as possible. The core project |
| 19 | + should be kept slim/lean. Installing Fileset should install as few |
| 20 | + sub-packages as possible. |
| 21 | +- Group code logically by file. A new contributor should be able to quickly |
| 22 | + understand the project structure and where to go to make code changes or |
| 23 | + enhancements – having too many files reduces scannability of the codebase. |
| 24 | + - Avoid creating new files that have just one function. Avoid creating new |
| 25 | + files to contain shared code until that code is used in more than one |
| 26 | + location. |
| 27 | +- Things should work "out of the box" for developers as frequently as possible. |
| 28 | + |
| 29 | +## Requirements |
| 30 | + |
| 31 | +- Avoid adding noise or extraneous information to command line utility output or |
| 32 | + visual UIs. |
| 33 | +- Make error messages clear and helpful. Put yourself in the user's shoes. When |
| 34 | + encountering a problem, an error message should provide the user with a path |
| 35 | + to fixing the error. |
| 36 | + |
| 37 | +## Writing and style |
| 38 | + |
| 39 | +- Be concise and consistent. |
| 40 | +- Include as few words as possible to convey what you're trying to say. |
| 41 | +- Use "Sentence case" for titles and labels. Avoid "Title Case" for labels. |
| 42 | +- Variable and function names should be concise but self-explanatory. |
| 43 | +- Git commit messages should start with a verb. The subject should not exceed |
| 44 | + one line. Example: |
| 45 | + |
| 46 | +``` |
| 47 | +Add support for atomic deployments |
| 48 | +``` |
| 49 | + |
| 50 | +## Pull request flow |
| 51 | + |
| 52 | +- Avoid merge commits. Use the "rebase and merge" strategy or "squash and merge" |
| 53 | + strategy (preferred for larger features or commits). |
| 54 | +- Preserve the PR# in commit message subjects so the relevant discussion can be |
| 55 | + found later. |
| 56 | +- Commits that can be merged directly to `main`: |
| 57 | + - Comments/documentation |
| 58 | + - Implementing functionality that has already been scaffolded |
| 59 | + - Tests |
| 60 | + - Code style fixes/improvements |
| 61 | + - Cleanup or removal of dead code |
| 62 | +- Commits that should be sent via pull requests: |
| 63 | + - Designing new user-facing core features |
| 64 | + - Reworking the overall structure of several files or the internals of data structures |
| 65 | +- When desinging new user-facing core features, send a draft pull request early |
| 66 | + so there is visibility into the development and rationale, and so that |
| 67 | + feedback can be provided. |
| 68 | + |
| 69 | +## Development workflow |
| 70 | + |
| 71 | +### Getting started |
| 72 | + |
| 73 | +1. Clone this project. |
| 74 | +2. Run `npm install`. |
| 75 | +3. Run `npm run dev` in one Terminal to start the watcher. The watcher invokes |
| 76 | + the TypeScript compiler when code is changed. |
| 77 | +4. Run `node ./dist/src/index.js` to invoke the CLI from the local project |
| 78 | + directory. |
| 79 | + |
| 80 | +### Running against other sites locally |
| 81 | + |
| 82 | +1. From Fileset's root directory, run `npm link`. This tells NPM to "install |
| 83 | + Fileset from this directory, instead of from npmjs.org" for any project that |
| 84 | + depends on Fileset. |
| 85 | +2. `cd` to the site's root directory. |
| 86 | +3. Ensure `@blinkk/fileset` is in the project's `package.json` dependencies. |
| 87 | +4. Run `npm install`. |
| 88 | +5. Invoking the `fileset` command will now point to your local development |
| 89 | + version instead of the one hosted on npmjs.org. |
| 90 | + |
| 91 | +To unlink (the order is important): |
| 92 | + |
| 93 | +1. `cd` to the site's root directory. |
| 94 | +2. Run `npm unlink --no-save @blinkk/fileset` |
| 95 | +3. `cd` to Fileset's root directory. |
| 96 | +4. Run `npm unlink` |
| 97 | + |
| 98 | +## Tips |
| 99 | + |
| 100 | +- We recommend using VSCode or a similar editor that supports autofixing and |
| 101 | + displaying TypeScript and ESLint code hints. |
| 102 | +- When using VSCode, we recommend the following extensions (see below). |
| 103 | + |
| 104 | +``` |
| 105 | +amatiasq.sort-imports |
| 106 | +dbaeumer.vscode-eslint |
| 107 | +``` |
| 108 | + |
| 109 | +- When using VSCode, we recommend enabling "Fix All on Save" (see below). |
| 110 | + |
| 111 | +``` |
| 112 | +# In VSCode's `settings.json` |
| 113 | +"editor.codeActionsOnSave": { |
| 114 | + "source.fixAll.eslint": true |
| 115 | +}, |
| 116 | +``` |
0 commit comments