Skip to content

Commit 24bb05a

Browse files
sa-fw-ansa-fw-an
authored
Merge pull request #3 from sa-fw-an/documentation
Add documentation
2 parents ff276c6 + 60064e8 commit 24bb05a

File tree

3 files changed

+259
-50
lines changed

3 files changed

+259
-50
lines changed

‎README.md‎

Lines changed: 46 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,46 @@
1-
# React + TypeScript + Vite
2-
3-
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
4-
5-
Currently, two official plugins are available:
6-
7-
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
8-
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
9-
10-
## Expanding the ESLint configuration
11-
12-
If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
13-
14-
- Configure the top-level `parserOptions` property like this:
15-
16-
```js
17-
export default tseslint.config({
18-
languageOptions: {
19-
// other options...
20-
parserOptions: {
21-
project: ['./tsconfig.node.json', './tsconfig.app.json'],
22-
tsconfigRootDir: import.meta.dirname,
23-
},
24-
},
25-
})
26-
```
27-
28-
- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
29-
- Optionally add `...tseslint.configs.stylisticTypeChecked`
30-
- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
31-
32-
```js
33-
// eslint.config.js
34-
import react from 'eslint-plugin-react'
35-
36-
export default tseslint.config({
37-
// Set the react version
38-
settings: { react: { version: '18.3' } },
39-
plugins: {
40-
// Add the react plugin
41-
react,
42-
},
43-
rules: {
44-
// other rules...
45-
// Enable its recommended rules
46-
...react.configs.recommended.rules,
47-
...react.configs['jsx-runtime'].rules,
48-
},
49-
})
50-
```
1+
<div align="center">
2+
3+
# [Sugar Labs](https://www.sugarlabs.org/)
4+
5+
# Sugar Labs web site
6+
7+
</div>
8+
9+
## Aims
10+
11+
* To announce our vision and mission,
12+
* To invite potential users of Sugar Labs software,
13+
* To advertise our free software and licensing approach,
14+
* To provide links to software downloads, and;
15+
* To invite potential developers to the source code we hold in trust.
16+
17+
## Contributing
18+
19+
Content on the site, that is information about Sugar, Sugarizer, or Music Blocks, is _way more important_ than the style or appearance.
20+
21+
Please concentrate on updating the content of the site, and not the style or appearance.
22+
23+
For your pull requests or issues to be taken seriously, you must be a user or developer of one of our software products; Sugar, Sugarizer, or Music Blocks.
24+
25+
For detailed information refer to the [Contribution's Guide](docs/CONTRIBUTING.md).
26+
27+
## Tech Stack
28+
29+
SugarWeb is a client-side web application written in TypeScript. React is used to render UI components, and the project is set up to independently use any JavaScript UI library/framework or the JS DOM API directly. It is bundled using Vite.
30+
31+
### Application
32+
33+
* TypeScript 5
34+
* React 19
35+
* Tailwind CSS
36+
37+
### Tooling
38+
39+
* Node.js
40+
* Vite
41+
* ESLint
42+
* Prettier
43+
44+
## Development
45+
46+
To get started with development refer to the [Developer Guide](docs/dev_guide.md).

‎docs/CONTRIBUTING.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Contributing Guide
2+
3+
## New Contributors
4+
5+
Use the [discussions](https://github.com/sugarlabs/www-v2/discussions/) tab at the top of
6+
the repository to:
7+
8+
- Ask questions you're wondering about.
9+
- Share ideas.
10+
- Engage with other community members.
11+
12+
Feel free. But, please don't spam :p.
13+
14+
## Keep in Mind
15+
16+
1. Your contributions need not necessarily have to address any discovered issue. If you encounter any,
17+
feel free to add a fix through a PR, or create a new issue ticket.
18+
19+
2. Use [labels](https://github.com/sugarlabs/www-v2/labels) on your issues and PRs.
20+
21+
3. Do not spam with lots of PRs with little changes.
22+
23+
4. If you are addressing a bulk change, divide your commits across multiple PRs, and send them one at
24+
a time. The fewer the number of files addressed per PR, the better.
25+
26+
5. Communicate effectively. Go straight to the point. Don't write unnecessary comments; don't be
27+
over-apologetic. Every single contribution is welcome, as long as it doesn't spam or distract the flow.
28+
29+
6. Write useful, brief commit messages. Add commit descriptions if necessary. PR name should speak
30+
about what it is addressing and not the issue. In case a PR fixes an issue, use `fixes #ticketno` or
31+
`closes #ticketno` in the PR's comment. Briefly explain what your PR is doing.
32+
33+
7. Always test your changes extensively before creating a PR. There's no sense in merging broken code.
34+
If a PR is a _work in progress (WIP)_, convert it to draft. It'll let the maintainers know it isn't
35+
ready for merging.
36+
37+
8. Read and revise the concepts about programming constructs you're dealing with. You must be clear
38+
about the behavior of the language or compiler/transpiler. See
39+
[JavaScript docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [TypeScript docs](https://www.typescriptlang.org/docs/).
40+
41+
9. If you have a question, do a _web search_ first. If you don't find any satisfactory answer, then
42+
ask it in a comment. If it is a general question, please use the new
43+
[discussions](https://github.com/sugarlabs/www-v2/discussions) tab on top the the repository, or
44+
the _Sugar-dev Devel <[sugar-devel@lists.sugarlabs.org](mailto:sugar-devel@lists.sugarlabs.org)>_ mailing
45+
list. Don't ask silly questions (unless you don't know it is silly ;p) before searching it on the web.
46+
47+
## Code Quality Notes
48+
49+
1. Sticking to _TypeScript_ conventions, use _camelCase_ for filenames (_PascalCase_ for _class_ files),
50+
_CAPITALCASE_ for constants, _camelCase_ for identifiers, and _PascalCase_ for _classes_. Linting has
51+
been strictly configured. A `super-linter` is configured to lint check the files on a pull request.
52+
In fact, the _TypeScript_ watcher or build will throw errors/warnings if there are linting problems.
53+
This has been done to maintain code quality.
54+
55+
2. If a PR is addressing an issue, prefix the branch name with the issue number. For example, say a
56+
PR is addressing issue `100`, a branch name could be `100-patch-foobar`.
57+
58+
3. Meaningfully separate code across commits. Don't create arbitrary commits. In case it gets dirty,
59+
please do an _interactive rebase_ with _squash_ and _reword_ to improve.
60+
61+
4. Follow [conventional commit messages specification](https://www.conventionalcommits.org/en/v1.0.0-beta.2/)
62+
to help issue tracking. More often than not, take time to add meaningful commit descriptions. However,
63+
add specificity by mentioning the component; prefer `feat(mycomponent): [UI] add button` over
64+
`feat: add button`, `fix(mycomponent): use try-catch` over `fix: use try-catch`, etc.
65+
66+
5. At any point, when new components are created or existing components are modified, unit tests (passing)
67+
reflecting the changes need to be part of the PR before being reviewed.
68+
69+
6. Two workflows -- a _Continuous Integration_ (_CI_) and a _Linter_ (_Super Linter_), have been configured.
70+
Each PR must pass the checks before being reviewed.
71+
72+
7. For any new functions/methods or classes, add extensive [TSDoc](https://tsdoc.org/) documentation.
73+
74+
8. Each PR needs to have supporting unit tests covering all (or as much practical) use cases to qualify
75+
for review. In case testing is done via some non-standard method, adequate description of the method/s
76+
need/s to be specified in the PR body.
77+
78+
## Checklist before Commits
79+
80+
- Make sure there are no _TypeScript_ warnings/errors. Run `npm run lint:ts` to verify.
81+
82+
- Make sure there are no linting errors in the Markdown. Run `npm run lint:md` to verify.
83+
84+
- Format code you've modified. Run `npm run format`.
85+
86+
- Make sure the application builds successfully. Run `npm run build` to verify.
87+
88+
- Add meaningful documentation to every new function/method/class/type added.
89+
90+
- One commit must address only one concept. Do not add multiple unrelated changes in one commit.

‎docs/dev_guide.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Developer's Guide
2+
3+
## Getting the code
4+
5+
1. Fork this repository,
6+
7+
2. Clone your forked copy of the project;
8+
9+
```bash
10+
git clone https://github.com/<your_user_name>/www-v2.git
11+
```
12+
13+
3. Change to the project directory;
14+
15+
```bash
16+
cd www-v2
17+
```
18+
19+
## Setup Development Environment
20+
21+
This is a _**TypeScript**_ project that uses _**React**_. You'll just need _[**Node.js**](https://nodejs.org/en) and _**npm**_ installed on your development machine.
22+
Although, this is sufficient to run, build, and test the project as a whole, you might need some
23+
extra tools for other development tasks.
24+
25+
You'll need _**tsc**_ (_TypeScript Compiler_) to manually compile `.ts` files. You'll need
26+
_**ts-node**_ (_Node.js executable for TypeScript_) to manually execute `.ts` scripts directly. Finally,
27+
you'll need an _HTTP_ server like _**http-server**_ (_a HTTP server program_), if you want to serve
28+
files manually.
29+
30+
Once _**npm**_ is installed, to install the above, run
31+
32+
```bash
33+
npm i -g http-server
34+
npm i -g typescript
35+
npm i -g ts-node
36+
```
37+
38+
_**Note:**_ Users on _Linux_ and _MacOS_ are required to add a `sudo` before these commands.
39+
40+
Check installation using
41+
42+
```bash
43+
node -v && npm -v && tsc -v && ts-node -v && http-server -v
44+
```
45+
46+
Output should look like
47+
48+
```bash
49+
v23.7.0
50+
11.1.0
51+
Version 5.7.3
52+
v10.9.2
53+
v14.1.1
54+
```
55+
56+
## Commands
57+
58+
After you are set-up, the steps you take depend on what you want to do:
59+
60+
- **Run a development server**
61+
62+
1. To install all the dependencies (in `package.json`), run
63+
64+
```bash
65+
npm install
66+
```
67+
68+
2. Run _React scripts_.
69+
70+
- For unoptimized development serving, run
71+
72+
```bash
73+
npm run dev
74+
```
75+
76+
Visit `localhost:5173` in a browser to view the web page served.
77+
78+
- For generating a generic production build, run
79+
80+
```bash
81+
npm run build
82+
```
83+
84+
- For generating a production build under the subdirectory `/www-v2`, run
85+
86+
```bash
87+
npm run build:gh
88+
```
89+
90+
- For serving the last production build (`dist` folder), run
91+
92+
```bash
93+
npm run preview
94+
```
95+
96+
Visit `localhost:4173` in a browser to view the web page served.
97+
98+
## Editor
99+
100+
_All code is just plain text, so it doesn't really matter what you use to edit them._ However,
101+
using modern, feature-rich IDEs/text-editors like:
102+
[_**Atom**_](https://github.blog/2022-06-08-sunsetting-atom/),
103+
[_**Brackets**_](https://brackets.io),
104+
[_**WebStorm**_](https://www.jetbrains.com/webstorm/),
105+
[_**Sublime Text**_](https://www.sublimetext.com/),
106+
[_**Visual Studio Code**_](https://code.visualstudio.com/), etc. makes life way easier. These come
107+
with a directory-tree explorer, and an integrated terminal, at the very least, while having support
108+
for plugins/extensions to expand their functionality.
109+
110+
Some (non-exhaustive) benefits of using these are _syntax highlighting_,
111+
_warning/error annotations_, _formatting_, _auto-refactoring_, tons of customizable
112+
_keyboard shortcuts_, etc.
113+
114+
_**Visual Studio Code**_ (_**VSCode**_) is currently the most-popular code editor for reasons like
115+
being _lightweight_, _cleaner_, large marketplace of _extensions_, integrated _source control_
116+
features, _debugger_, _remote explorer_ support, _regular expression_ based find/replace, etc.
117+
118+
In fact, a workspace configuration file for _vscode_`.vscode/settings.json` has already been added.
119+
Recommended extensions for this project are `Babel JavaScript`, `ESLint`, `Git Graph`,
120+
`GitLens`, `markdownlint`, `Prettier`, `Tailwind CSS IntelliSense`, and `SVG`.
121+
122+
All that, however, shouldn't necessarily stop you from using _**Emacs**_, _**Nano**_, or _**Vim**_,
123+
if that's your poison :D. Happy coding!

0 commit comments

Comments
 (0)