|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to the React Docs! |
| 3 | +תודה על הרצון לתרום לתיעוד של React. |
4 | 4 |
|
5 | 5 | ## Code of Conduct |
6 | 6 |
|
7 | | -Facebook has adopted a Code of Conduct that we expect project |
8 | | -participants to adhere to. Please [read the full text](https://code.facebook.com/codeofconduct) |
9 | | -so that you can understand what actions will and will not be tolerated. |
| 7 | +יש לפעול לפי קוד ההתנהגות של הפרויקט: |
| 8 | +https://code.facebook.com/codeofconduct |
10 | 9 |
|
11 | | -## Technical Writing Tips |
| 10 | +## הנחיות כתיבה |
12 | 11 |
|
13 | | -This is a [good summary](https://medium.com/@kvosswinkel/coding-like-a-journalist-ee52360a16bc) for things to keep in mind when writing technical docs. |
| 12 | +לתיעוד יש אזורים שונים עם מטרות שונות, ולכן גם סגנון שונה. כשעורכים דף קיים, שומרים על הטון של אותו אזור. |
14 | 13 |
|
15 | | -## Guidelines for Text |
| 14 | +1. `Learn React`: |
| 15 | + - בנוי כלמידה הדרגתית |
| 16 | + - יש להימנע מתלויות מחזוריות בין דפים |
| 17 | + - קורא אמור להיות מסוגל לעבור מהדף הראשון לאחרון ללא "קפיצות קדימה" |
| 18 | +2. `API Reference`: |
| 19 | + - מאורגן לפי APIs |
| 20 | + - צריך להיות מקיף ומדויק |
| 21 | + - מקרי קצה והמלצות מפורטות צריכים להופיע כאן |
16 | 22 |
|
17 | | -**Different sections intentionally have different styles.** |
| 23 | +## הנחיות לקוד בדוגמאות |
18 | 24 |
|
19 | | -The documentation is divided into sections to cater to different learning styles and use cases. When editing an article, try to match the surrounding text in tone and style. When creating a new article, try to match the tone of the other articles in the same section. Learn about the motivation behind each section below. |
| 25 | +1. העדיפו JSX על `createElement` (אלא אם הדף עוסק ספציפית ב-`createElement`). |
| 26 | +2. העדיפו `const`, ואם צריך אז `let`; לא להשתמש ב-`var`. |
| 27 | +3. אם אין יתרון ברור ל-ES6 חדש, אפשר להשתמש ב-ES5 ברור ופשוט. |
| 28 | +4. לדוגמאות ברמת top-level, לרוב עדיף `function` בשם מאשר arrow function. |
| 29 | +5. אין להשתמש ביכולות לא סטנדרטיות בלי לציין במפורש שהן ניסיוניות. |
20 | 30 |
|
21 | | -**[Learn React](https://react.dev/learn)** is designed to introduce fundamental concepts in a step-by-step way. Each individual article in Learn React builds on the knowledge from the previous ones, so make sure not to add any "cyclical dependencies" between them. It is important that the reader can start with the first article and work their way to the last Learn React article without ever having to "look ahead" for a definition. This explains some ordering choices (e.g. that state is explained before events, or that "thinking in React" doesn't use refs). Learn React also serves as a reference manual for React concepts, so it is important to be very strict about their definitions and relationships between them. |
| 31 | +## סגנון קוד |
22 | 32 |
|
23 | | -**[API Reference](https://react.dev/reference/react)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Learn React should be mentioned in the reference documentation for the corresponding APIs. |
| 33 | +1. להשתמש ב-`;` |
| 34 | +2. אין רווח בין שם פונקציה לסוגריים |
| 35 | +3. במקרה של ספק, להיצמד ל-Prettier |
24 | 36 |
|
25 | | -**Try to follow your own instructions.** |
| 37 | +## הדגשת שורות בקוד Markdown |
26 | 38 |
|
27 | | -When writing step-by-step instructions (e.g. how to install something), try to forget everything you know about the topic, and actually follow the instructions you wrote, a single step at time. Often you will discover that there is implicit knowledge that you forgot to mention, or that there are missing or out-of-order steps in the instructions. Bonus points for getting *somebody else* to follow the steps and watching what they struggle with. Often it would be something very simple that you have not anticipated. |
| 39 | +שפת הדגשה: |
28 | 40 |
|
29 | | -## Guidelines for Code Examples |
30 | | - |
31 | | -### Syntax |
32 | | - |
33 | | -#### Prefer JSX to `createElement`. |
34 | | - |
35 | | -Ignore this if you're specifically describing `createElement`. |
36 | | - |
37 | | -#### Use `const` where possible, otherwise `let`. Don't use `var`. |
38 | | - |
39 | | -Ignore this if you're specifically writing about ES5. |
40 | | - |
41 | | -#### Don't use ES6 features when equivalent ES5 features have no downsides. |
42 | | - |
43 | | -Remember that ES6 is still new to a lot of people. While we use it in many places (`const` / `let`, classes, arrow functions), if the equivalent ES5 code is just as straightforward and readable, consider using it. |
44 | | - |
45 | | -In particular, you should prefer named `function` declarations over `const myFunction = () => ...` arrows for top-level functions. However, you *should* use arrow functions where they provide a tangible improvement (such as preserving `this` context inside a component). Consider both sides of the tradeoff when deciding whether to use a new feature. |
46 | | - |
47 | | -#### Don't use features that aren't standardized yet. |
48 | | - |
49 | | -For example, **don't** write this: |
50 | | - |
51 | | -```js |
52 | | -class MyComponent extends React.Component { |
53 | | - state = {value: ''}; |
54 | | - handleChange = (e) => { |
55 | | - this.setState({value: e.target.value}); |
56 | | - }; |
57 | | -} |
58 | | -``` |
59 | | - |
60 | | -Instead, **do** write this: |
61 | | - |
62 | | -```js |
63 | | -class MyComponent extends React.Component { |
64 | | - constructor(props) { |
65 | | - super(props); |
66 | | - this.handleChange = this.handleChange.bind(this); |
67 | | - this.state = {value: ''}; |
68 | | - } |
69 | | - handleChange(e) { |
70 | | - this.setState({value: e.target.value}); |
71 | | - } |
72 | | -} |
73 | | -``` |
74 | | - |
75 | | -Ignore this rule if you're specifically describing an experimental proposal. Make sure to mention its experimental nature in the code and in the surrounding text. |
76 | | - |
77 | | -### Style |
78 | | - |
79 | | -- Use semicolons. |
80 | | -- No space between function names and parens (`method() {}` not `method () {}`). |
81 | | -- When in doubt, use the default style favored by [Prettier](https://prettier.io/playground/). |
82 | | - |
83 | | -### Highlighting |
84 | | - |
85 | | -Use `js` as the highlighting language in Markdown code blocks: |
86 | | - |
87 | | -```` |
| 41 | +````md |
88 | 42 | ```js |
89 | 43 | // code |
90 | 44 | ``` |
91 | 45 | ```` |
92 | 46 |
|
93 | | -Sometimes you'll see blocks with numbers. |
94 | | -They tell the website to highlight specific lines. |
95 | | - |
96 | | -You can highlight a single line: |
| 47 | +הדגשת שורה בודדת: |
97 | 48 |
|
98 | | -```` |
| 49 | +````md |
99 | 50 | ```js {2} |
100 | 51 | function hello() { |
101 | | - // this line will get highlighted |
| 52 | + // highlighted |
102 | 53 | } |
103 | 54 | ``` |
104 | 55 | ```` |
105 | 56 |
|
106 | | -A range of lines: |
| 57 | +טווח שורות: |
107 | 58 |
|
108 | | -```` |
| 59 | +````md |
109 | 60 | ```js {2-4} |
110 | 61 | function hello() { |
111 | | - // these lines |
112 | | - // will get |
113 | | - // highlighted |
| 62 | + // highlighted range |
114 | 63 | } |
115 | 64 | ``` |
116 | 65 | ```` |
117 | 66 |
|
118 | | -Or even multiple ranges: |
| 67 | +כמה טווחים: |
119 | 68 |
|
120 | | -```` |
| 69 | +````md |
121 | 70 | ```js {2-4,6} |
122 | 71 | function hello() { |
123 | | - // these lines |
124 | | - // will get |
125 | | - // highlighted |
| 72 | + // highlighted lines |
126 | 73 | console.log('hello'); |
127 | | - // also this one |
| 74 | + // also highlighted |
128 | 75 | console.log('there'); |
129 | 76 | } |
130 | 77 | ``` |
131 | 78 | ```` |
132 | 79 |
|
133 | | -Be mindful that if you move some code in an example with highlighting, you also need to update the highlighting. |
| 80 | +אם מזיזים קוד בדוגמה, צריך לעדכן גם את שורות ההדגשה. |
| 81 | + |
| 82 | +## תהליך עבודה |
| 83 | + |
| 84 | +### יצירת branch |
| 85 | + |
| 86 | +1. עברו ל-`main` מכל תיקייה בריפו המקומי: |
| 87 | + - `git checkout main` |
| 88 | +2. משכו את העדכונים האחרונים: |
| 89 | + - `git pull origin main` |
| 90 | +3. צרו branch חדש עם שם מתאים: |
| 91 | + - `git checkout -b the-name-of-my-branch` |
| 92 | + |
| 93 | +### ביצוע השינוי |
| 94 | + |
| 95 | +1. פעלו לפי הוראות `Running locally`. |
| 96 | +2. שמרו את הקבצים ובדקו בדפדפן. |
| 97 | +3. שינויים בקומפוננטות React תחת `src` ייטענו עם `hot-reload`. |
| 98 | +4. שינויים בקובצי Markdown תחת `content` ייטענו עם `hot-reload`. |
| 99 | +5. אם עובדים עם plugins, ייתכן שתצטרכו למחוק את תיקיית `.cache` ולהפעיל את השרת מחדש. |
| 100 | + |
| 101 | +### בדיקות |
| 102 | + |
| 103 | +1. אם אפשר, בדקו כל שינוי ויזואלי בגרסאות האחרונות של דפדפנים נפוצים, גם בדסקטופ וגם במובייל. |
| 104 | +2. הריצו: |
| 105 | + - `yarn check-all` |
| 106 | +3. הפקודה מריצה `Prettier`, `ESLint` ובדיקת types. |
| 107 | + |
| 108 | +### Commit ו-Push |
| 109 | + |
| 110 | +1. בצעו stage ו-commit: |
| 111 | + - `git add -A && git commit -m "My message"` |
| 112 | +2. העלו את ה-branch: |
| 113 | + - `git push my-fork-name the-name-of-my-branch` |
| 114 | +3. היכנסו לריפו של `react.dev` ב-GitHub ותראו את ה-branches שהועלו לאחרונה. |
| 115 | +4. המשיכו לפי ההנחיות של GitHub לפתיחת PR. |
| 116 | +5. אם אפשר, צרפו צילומי מסך לשינויים ויזואליים. לאחר push ל-GitHub יופעל גם preview build. |
| 117 | + |
| 118 | +## תרגום לעברית |
| 119 | + |
| 120 | +בעת תרגום דפים: |
134 | 121 |
|
135 | | -Don't be afraid to often use highlighting! It is very valuable when you need to focus the reader's attention on a particular detail that's easy to miss. |
| 122 | +1. משאירים קוד, שמות APIs, פונקציות ופקודות באנגלית. |
| 123 | +2. מתרגמים כותרות, פסקאות והסברים לעברית. |
| 124 | +3. שומרים על מבנה Markdown/MDX ועל Frontmatter תקין. |
| 125 | +4. שומרים על עקביות מונחים בין דפים. |
0 commit comments