Changes between Version 9 and Version 10 of StudentTips

Timestamp:

2011-08-26T14:11:56Z (13 years ago)

Author:

Jakub Jermář

Comment:

Improve tips.

StudentTips

@@ -1 @@
-= Tips for students =
+= Tips for (not only) students =
 
 On this page, we provide tips for authors of HelenOS master and bachelor theses, and various software projects. The tips are based on previous experience in this area. For official guidance, please consult your thesis / project supervisor.
@@ -15 +15 @@
 
 == Implementation ==
-  * Stick to the [http://www.helenos.org/cstyle HelenOS coding style].
+  * Stick to the [http://www.helenos.org/cstyle HelenOS coding style]. We really mean this. Your failure to adhere to the coding style of the surrounding code requires someone else's extra work to perform the cleanup after you. The fact that you may prefer another coding style is quite insignificant in the context of HelenOS. Get over it and use our coding style.
   * Adhere to good coding practices, such as adequate commenting, avoiding dense code, using horizontal spacing as visual delimiter and keeping the block nesting level under control.
   * Self-contained code is good, but avoid poorly integrated code. Poorly integrated code is pointlessly concentrated in one subdirectory of the source tree. For example, putting new generic ADT's and IPC primitives under the networking directory is a sign of poorly integrated code.
   * As with the text of your thesis, similar citation rules should apply in your code. When using third party code, always give credit where the credit is due, always follow the license of the third party code. It would be kind of embarrassing to discover portions of e.g. Linux header file in code which you advertise as yours.
   * Be open-minded. If you are designing a new subsystem or some sort of interface for HelenOS, it may be convenient to do it exactly how it is done in e.g. Linux. Please don't do that, especially not if the only reason would be because Linux does it that way. Remember that cloning a legacy system is not our goal. When evaluating approaches to a problem in other operating systems, use critical thinking and try to find problems of and ways to improve their solutions.
+  * Always use English for writing comments.
+
+== Source history
+  * Remember that the revision control system does not forget things. Whatever you commit to your local branch will often eventually be merged into the HelenOS mainline repository.
+  * Always use English for writing commit logs.
+  * Give some extra love to formulating your commit logs. You may consider providing one summary line followed by an empty line and a bullet list of more detailed description of each change.
+  * Try to make more smaller commits than few larger commits.
+  * Unrelated changes should go into separate commits.
+  * Don't forget to review your changes before committing them.
 
 == Interacting with the community ==
   * The HelenOS community can provide invaluable feedback to your ideas so make sure to interact with the community effectively. Simply put, participate on the mailing list and, if possible, attend the monthly project meetings.
+  * Prefer open communication on the mailing list over one-to-one private communication of any sort.
+  * Consider hanging around on our [irc://irc.freenode.net/helenos IRC channel].
+  * Don't be shy, we don't bite.