הנחיות תרומה
Welcome to the contribution guidelines for the frc-docs project. If you are unfamiliar to writing in the reStructuredText format, please read up on it here.
חשוב
FIRST® retains all rights to documentation and images provided. Credit for articles/updates will be in the GitHub commit history.
הצהרת משימה
המשימה של WPILib היא לאפשר לקבוצות FIRST להתמקד בכתיבת התוכנה הספציפית למשחק במקום להתמקד בפרטי החומרה - ״הרימו את הרצפה, אל תנמיכו את התקרה״. אנו פועלים כדי לאפשר לקבוצות בעלי ידע מוגבל בתכנות ו/או נסיון מנטורים מוגבל להצליח ככל האפשר, ללא פגיעה ביכולות של קבוצות בעלות יכולות תכנות מתקדמות יותר. אנו תומכים במרכיבי מערכת הבקרת של ה-Kit of Parts ישירות בספריה. אנו שואפים לשמור על שוויון בין התכונות העיקריות של כל שפה (Java, C++, ו-LabVIEW של NI), כך שלא יהיה חיסרון לקבוצות בבחירת שפת תכנות ספציפית.
מסמכים אלו משמשים כבסיס למידה לכל קבוצות FIRST Robotics Competition. על התרומות לפרויקט להיות בהתאם לעקרונות הליבה הללו.
תיעוד מונחה קהילה. קוד המקור של התיעוד מתארח בפומבי והקהילה יכולה לבצע תרומות
תיעוד מאורגן, מעוצב ונקי. התיעוד צריך להיות נקי וקל לקריאה, הן מהמקור והן מצד התוצר
רלוונטי. על התיעוד להתמקד ב-FIRST Robotics Competition
אנא עיינו במסמך הנחיות סגנון למידע על עיצוב סגנון התיעוד.
Release Process
frc-docs uses a special release process for handling the main site /stable/
and the development site /latest/
. This flow is detailed below.
During Season:
Commit made to
main
branchUpdates
/stable/
and/latest/
on the website
End of Season:
Repository is tagged with year, for archival purposes
Off-Season:
stable
branch is locked to the last on-season commitCommit made to
main
branchOnly updates
/latest/
on the documentation site
Creating a PR
PRs should be made to the frc-docs repo on GitHub. They should point to the main
branch and not stable
.
Creating New Content
Thanks for contributing to the frc-docs project! There are a couple things you should know before getting started!
Where to place articles?
The location for new articles can be a pretty opinionated subject. Standalone articles that fall well into an already subject category should be placed into mentioned subject category (documentation on something about simulation should be placed into the simulation section). However, things can get pretty complicated when an article combines or references two separate existing sections. In this situation, we advise the author to open an issue on the repository to get discussion going before opening the PR.
הערה
כל המאמרים החדשים יעברו תהליך בדיקה לפני מיזוגם ל-Repository. תהליך הבדיקה ייעשה על ידי חברי צוות WPILib. מאמרים חדשים חייבים להיות נתמכים רשמית על ידי FIRST בתוכנה ובחומרה. תיעוד על ספריות או חיישנים לא רשמיים לא יתקבל. תהליך הבדיקה עשוי לקחת זמן מה, אנא התאזרו בסבלנות.
Where to place sections?
Sections are quite tricky, as they contain a large amount of content. We advise the author to open an issue to gather discussion before opening up a PR.
Linking Other Articles
In the instance that the article references content that is described in another article, the author should make best effort to link to that article upon the first reference.
Imagine we have the following content in a drivetrain tutorial:
Teams may often need to test their robot code outside of a competition. :ref:`Simulation <link-to-simulation:simulation>` is a means to achieve this. Simulation offers teams a way to unit test and test their robot code without ever needing a robot.
Notice how only the first instance of Simulation is linked. This is the structure the author should follow. There are times where a linked article has different topics of content. If you reference the different types of content in the article, you should link to each new reference once (except in situations where the author has deemed it appropriate otherwise).