Skip to content

Commit 80725cf

Browse files
Toniolo-MarcoToniolo-Marco
authored
Update README.md
Update README.md with SW components, common crate info, documentation and teacher spec
1 parent 80a9ed4 commit 80725cf

File tree

1 file changed

+201
-7
lines changed

1 file changed

+201
-7
lines changed

‎profile/README.md

+201-7
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,215 @@
11
# Expected workflow
22

3-
1) the group leader should **open an issue** with what you intend to do, giving it an explanatory title and a detailed description (you are strongly encouraged to use the labels to add details)
4-
2) the group leader should **fork the main branch** into a local repository, making changes together with other members of teh group
5-
3) the group leader should **open a pull request** to bring the changes made in the personal repository into the main
6-
4) **wait** for one of the owner group members ([@MatteoPossamai](https://github.com/MatteoPossamai), [@DavideC03](https://github.com/DavideC03) and [@FrostWalk](https://github.com/FrostWalk)) of the GitHub organization to **accept the pull request** after a brief review
3+
1. the group leader should **open an issue** with what you intend to do, giving it an explanatory title and a detailed description (you are strongly encouraged to use the labels to add details)
4+
2. the group leader should **fork the main branch** into a local repository, making changes together with other members of teh group
5+
3. the group leader should **open a pull request** to bring the changes made in the personal repository into the main
6+
4. **wait** for one of the owner group members ([@MatteoPossamai](https://github.com/MatteoPossamai), [@DavideC03](https://github.com/DavideC03) and [@FrostWalk](https://github.com/FrostWalk)) of the GitHub organization to **accept the pull request** after a brief review
7+
5. You must **document** the new code with [doc comments](https://doc.rust-lang.org/reference/comments.html#doc-comments)
78

89
It's not necessary to contact us to have pull requests accepted, we receive a notification whenever one is opened, in case a request is rejected, the causes will be specified in a comment in the pull requst.
910
The ability to perform **push directly on the main** and **auto accept pull requests** has been **disabled**.
1011

1112
A system will soon be implemented that will publish the code on the Common Crate as soon as a change is made to the main.
1213

14+
## A note on Rustfmt
1315

14-
# A note on Rustfmt
1516
To avoid conflicts given by different code formatting, a configuration file for Rustfmt is present in the root of the project, follow this tutorial to enable RustFmt in JetBrains IDEs
1617
https://github.com/rust-lang/rustfmt/blob/master/intellij.md
1718

18-
# Documentation
19+
## Documentation
20+
1921
A version of the documentation extracted from the Drive document and transcribed into MarkDown for ease of viewing, organized by category can be found in this [repository](https://github.com/Advanced-Programming-2023/Documentation),
20-
to request that changes be made, proceed to edit the file on Drive following the predetermined procedure and if necessary contact the documentation manager [@Toniolo-Marco](https://github.com/Toniolo-Marco),
22+
to request that changes be made, proceed to edit the file on Drive following the predetermined procedure and if necessary contact the documentation manager [@Toniolo-Marco](https://github.com/Toniolo-Marco),
2123
as you can imagine the **transcription process is not instantaneous**, so it is possible that **after a meeting** the documentation **may not be up-to-date** for a couple of days.
24+
25+
# Overview of the Project
26+
27+
## Individuals
28+
29+
Each group member has to develop an individual contribution, which is:
30+
31+
- Robot AI, meaning, some basic logic, that uses tools and/or interfaces to control a robot in the world following a Mission
32+
- UI Displayer, which displays what a robot is doing in the world.
33+
34+
## Working Groups
35+
36+
We are organized in groups of 4 people, with some exceptions of 3 people. Each group will be responsible of developing:
37+
38+
- 1 virtual robot, it interacts with a world, moving, and doing some basic tasks on the world.
39+
- 1 tool (sensor or actuator).
40+
- 1 world generator or another tool.
41+
42+
## WGL (Working Group Leader)
43+
44+
One of the 4 people in the working group, they are responsible for voting changes to the Specifications (they are the only ones that can vote). The list of WGL can be found in **notes** below.
45+
46+
## WGC (Working Group Coordinator)
47+
48+
Also known as scapegoat, is responsible of making the various meetings productive, drafting each new version of the Specifications and to submit the shared code to the repo. Our WGC is [Matteo Possamai](https://t.me/poss03251)
49+
50+
## Sub-Working Group
51+
52+
~~A team of 7 people that will have to decide about a specific problem. (what does the World contain, how the World Generation works etc...)~~ (This is not used anymore)
53+
54+
---
55+
56+
# SW Components
57+
58+
## Common Crate
59+
60+
The Commons Crate is the only crate that is shared among all groups. It contains following modules:
61+
62+
- World
63+
- Interface
64+
- Runner
65+
- Energy
66+
- Test
67+
- Utils
68+
69+
## World
70+
71+
A World is a 2d grid whose cells contain various things: grass, water, fire, trees, bins. It is defined in the Commons Crate.
72+
73+
## Interfaces
74+
75+
The only way to interact with the World is through Interfaces, these are described in the doc and only implemented in the Commons Crate.
76+
77+
Interfaces allow limited sensing (reading) of the world and limited acting (writing) on the world. (except for the debug interface, **test purposes only**)
78+
79+
Some Interfaces require some Energy to work, and Energy is created in the Commons Crate. Also Interfaces are implemented in the Commons Crate.
80+
81+
## Runner
82+
83+
The module that manage the runtime logic and contains both the definition of a robot and the trait it must implement.
84+
85+
## Energy
86+
87+
The module that contains the definition of the energy and its methods.
88+
89+
## Test
90+
91+
Here you can find the tests for the Commons Crate, you can run them with the command `cargo test` in the Commons Crate folder or, using a JetBrains IDE, you can run them with `test --package robotics_lib --lib tests::testing -- --exact` as command.
92+
93+
## Utils
94+
95+
Here you can find all the utilities functions used in the Commons Crate.
96+
97+
## Robot
98+
99+
A robot receives a fixed amount of energy each tick, with which it should hopefully complete its task, using sensors and actuators (developed by other groups).
100+
101+
## Tools
102+
103+
In order for a Robot to use an Interface, teams will implement Tools.
104+
These Tools combine Interfaces to grant the robot elaborate functionalities provided the Robot has enough energy.
105+
106+
For example, a Tool can put out all the fires in a row, by iterating over the put-out-fire and move Interfaces.
107+
108+
---
109+
110+
# Stages of Development
111+
112+
1. Early Stage: During the first few weeks, Working Group Leaders will meet in different meetings to agree on the specs and fix them. This corrispond to the branch out of sub-Working Groups.
113+
2. Implementation of the Commons Crate: initial individual contributions and component development can begin: world generator and sensors; within each working group.
114+
3. Freezing the Specification (**max 21st class**): As the semester approaches its end, the Specifications will be considered _frozen_ with no further modifications allowed, except for correcting typos. To unfreeze the Specifications, the WGC needs consensus from the WGL (≥ 51%). If the request is deemed reasonable, the Specifications is unfrozen for one meeting, finalized, and then frozen again. Unfreezing is discouraged as it may lead to changes in **your** code, and excessive unfreezing reflects negatively on the WGL and WGC evaluations. It is advised to work towards a stable Specifications to avoid the need for unfreezing.
115+
4. Faire (**5th Dec**): At some point in Povo, there will be an actual faire, where each group will sell and buy sensors and world generators. You have to **come with working versions of your sensors, show that they comply to the agreed Specification** and convince other groups to commit to your code and not to other groups. During the Faire, each group must commit to use: **at least one World Generator, at least 7 Sensors**. Each group's choices will be registered at the end of the faire. These choices are final, and in the final project evaluation, your robot will have to run with the crates you are committed to. (The first three groups whose code is committed-to the most will have a grade bonus)
116+
5. Robot Development and Maintenance: During this phase, different working groups will be tasked with developing their own robot, with only the sensors purchased from other groups. In addition, each group will have to provide support for previously produced components to client groups.
117+
118+
---
119+
120+
# Class Code Repository
121+
122+
## Setup
123+
124+
Each group's sensors, plus any shared code will be hosted on the class registry, available at: https://advancedprogramming.disi.unitn.it/ .
125+
126+
You will recive your personal access token for pushing and pulling crates from the registry. The group will be registered with the access tokens of all its members in order for you to push and pull group code.
127+
128+
You need to add a file to your project in `.cargo/config.toml` with the following lines:
129+
130+
```
131+
[registries]
132+
kellnr = { index = "git://advancedprogramming.disi.unitn.it/index",
133+
token = "put your token here between quotes"}
134+
```
135+
136+
## Pulling code
137+
138+
You can then edit the file `Cargo.toml` and include lines such as these:
139+
140+
```
141+
[dependencies]
142+
test = { version = "0.1.1", registry = "kellnr"}
143+
```
144+
145+
where instead of `test`, you import your colleagues component.
146+
147+
## Pushing your code
148+
149+
In order to push your market, you need to edit the file `Cargo.toml` and include lines such as these
150+
151+
```
152+
[package]
153+
name = " your robot name"
154+
version = "0.1.2"
155+
edition = "2023"
156+
authors = ["your names"]
157+
publish = ["kellnr"]
158+
#do not modify the "publish" key, this is the name of the registry
159+
# as read from the ".cargo/config.toml" file
160+
```
161+
162+
and use the command
163+
`cargo publish`
164+
to publish the crate to the mentioned registry.
165+
166+
# Notes
167+
168+
## Code principles
169+
170+
In all the code you write (for the WG, or in the implementations of your group, or the final project) you must keep present this principles:
171+
172+
- each of the crates your group publishes on the Registry must have the group name (or an acronym) in its own name. The names must be explicit of the crate content.
173+
- no unsafe code
174+
- no undocumented panic!
175+
- the code must be extensively tested, and you should not preclude crates downstream to test their code
176+
- expose through public interfaces only what is strictly needed, and only that
177+
- write idiomatic code
178+
179+
Please
180+
181+
## List of WGL
182+
183+
- Rust and Furious: Sara Francavilla
184+
- Rusty Krab: [Loan Gabriel Duta](https://t.me/bagzziii)
185+
- Fe₂O₃: [Morgana Pasquini](https://t.me/Rulaanxxvii)
186+
- The rust of us: [Alessio Amiri](https://t.me/SpaghettiMan69)
187+
- Rustbeef: [Thomas Pasquali](https://t.me/thom_pasqui)
188+
- Cargo commandos: [Niccolò Eccel](https://t.me/Neo3010)
189+
- Crab Rave: [Alessio Faieta](https://t.me/alessiofaieta)
190+
- ＲｕｓｔｙＰｒｉｐｙａｔ ☭ ʖ ☭: [Toniolo Marco](https://t.me/marco_toniolo)
191+
- Ownersheeps: Gabriele Bazzanella Bauer
192+
- I Rustici: Federico Menegoz
193+
- Rust-eze: [Guglielmo Boi](https://t.me/guglielmoboi)
194+
- Another one bytes the Rust: [Corradini Dimitri](https://t.me/dimi56497)
195+
- tRust us: Matteo Frigo
196+
- WhoNeedsGV: Marco Antonio Murru
197+
- #![allow(bad_code)]: [Silvanus Bordignon](https://t.me/silvanusbordignon)
198+
- do not panic!(): Marco Pulze
199+
- tyrannosauRust-rex: [Giovanni Foletto](https://t.me/GiovanniFoletto)
200+
- (\\/)('-')(\\/): [Nicolò Marchini](https://t.me/praisethefab)
201+
- .unwrap().unwrap().unwrap(): [Andrea Bissoli](https://t.me/AndreaBissoli)
202+
- Pattern-Matching Pioneers: Davide José Paci
203+
- antiRust: Andrea Richichi
204+
- I fRustati: [Denise Comincioli](https://t.me/DeathOnABicycle)
205+
- Turbofish Team: [Gianluca Rigatti](https://t.me/gian03r)
206+
- Rust in peace: [Podavini Luca](https://t.me/lucapoda)
207+
- OhCrab: Kateřina Průšová
208+
- OxidizingAgents: [Filippo Lollato](https://t.me/lolfilippo)
209+
- Holy Crab: Davide Pedrotti
210+
- Ραστανιδουμεν:Artem Buev
211+
- Rustafariani: Rodrigo Salas
212+
- 1v1 on Rust?: Claudio Vozza
213+
- Ghost Rusters: [Ludovico Cappellato](https://t.me/ludo_cappe)
214+
- arRusticini: [Federico Cucino](https://t.me/federicocuci)
215+
- CongRUSTulazioni: Marco Demo

0 commit comments

Comments
 (0)