Skip to content

CONTRIBUTE.md

Latest commit

 

History

History
66 lines (53 loc) · 5.82 KB

CONTRIBUTE.md

File metadata and controls

66 lines (53 loc) · 5.82 KB

How to publish your work in an ABS repository

Despite the ABS GitHub repositories being open to the community, they are internally managed and are subject to reviews. The review process prevents the master repo from containing wrong, incomplete or inconsistent code (or designs), and is oriented to provide detailed feedback on your proposed implementations. The ABS repositories are peer-reviewed by M. Marí (mark-mb) and C. Araguz (carlesaraguz), who will post their comments to you implementations through this GitHub web platform. The review process is decomposed into the following steps:

  1. You fork the ABS repo in which you will be working (Software, Hardware or ARTOS).
  2. Push your local commits to your forked repo.
  3. Include a detailed README.md file explaining how to open/compile/test your files. Remember to include references to other communities (e.g. other repo's) if you have used libraries or special assets. External assets such as libraries, should not be included in ABS repo's unless it is strictly necessary (see note below).
  4. Issue a pull-request.
  5. In your pull-request form, provide thorough details of your changes, design, important sections or aspects that you consider important during the review process (e.g. unimplemented sections, purposefully ignored warnings and their justification, hard-coded parts that you expect to modify later, etc.)
  6. The reviewers will read, compile and execute your code and provide feedback.
  7. Then:
    • If your pull-request is accepted but requires some changes, you should provide them in the form of a new pull-request (step 4). The master repository will include your previous commits.
    • If your pull-request is rejected, you need to fix your issues as soon as possible and generate a new pull-request (step 4). Remember that if this happened after the FDR, your course mark may rely on this second/fixed pull-request.

General recommendations

  • Start working on your local repository from the beginning. Using a GIT repository not only will allow you to recover previous versions or keep your developments well organised but will also allow you to issue several pull-requests during the course (and have them reviewed before the FDR).
  • Coordinate your efforts with the rest of collaborators so that you work in the appropriate folder from the beginning. Remember that the repository structure and file naming is also managed and has to be agreed with the rest of team members.
  • Read the repository's rules carefully (e.g. CODING_STYLES.md) before issuing your pull-requests.

A note about external libraries or assets

You may include external code or designs (e.g. libraries) if:

  • The external assets comply to the repository rules (i.e. no binaries, well documented, open-source, etc.)
  • You have performed some modifications to those assets or you are using modified versions that can't be get from official sources.
  • You always give credit to the original author(s) / source(s).
  • You justify your decision.

General rules for the ABS software repository (abs-software)

These repositories shall only include software-related development such as: software architecture modules, Arduino firmware, microcontroller's firmware. The repo must never include:

  • Project files (i.e. the kind of garbage left by programming IDE's such as NetBeans, Eclipse or MPLAB)
  • Autogenerated Makefiles that can only be executed by the programming IDE.
  • Binaries or built sources.
  • Programs that are not compliant with the coding styles (exception: code that you have not written, such as external libraries or headers).

General rules for the ABS hardware repository (abs-hardware)

Given that most PCB design frameworks don't usually generate text files, hardware designs must be kept in different folders according to their version. For PCB designs, the following (minimum) files have to be included:

  • The schematic (e.g. ".SchDoc")
  • The PCB layout (e.g. ".PcbDoc")
  • A PDF file with the schematic (organised in several pages, if needed) and layout (in a way that all layers can be seen, e.g. each layer in a different page).
  • The fabrication files (layers in Gerber format), as they would be sent to the manufacturer company.
  • A bill-of-materials Excel (or LibreOffice / Google Docs spreadsheet) with, at least, the following columns:
    • The component description and value (e.g. "Resistor 1k2", "RF transmitter", "Inductor 23 mH");
    • the component name(s) as shown in schematics and silk-screen layer (e.g. IC23, C34, R2, L1);
    • the manufacturer's reference (e.g. LT3129);
    • the footprint/case reference;
    • the purchasing reference (e.g. Farnell product ID) and a descriptive comment;
    • and the quantity.
  • A README.md file with stating:
    • The version number and name of the software that has been used to generate the files (e.g. "Altium Designer v15.43.2")
    • Special fabrication requirements, if any (e.g. FR4 substrate).

May be included in the repository: footprint libraries for non-standard components, a Datasheets folder containing PDF component datasheets.

Folder naming

All PCB designs must be placed in folders applying the following naming rules:

UPCNSL-ABS-XXX-YYY-vN.NN

Where:

  • UPC-NSL-ABS is the generic codename for ABS boards from the NanoSat Lab / UPC.
  • XXX is the subsystem: ARDS (for Arduino Space board), EPS (Electrical Power Subsystem boards, such as the PV panels), POL (for Point-of-Load boards), COMMS (for RF boards of the comms. subsystem).
  • YYY is a secondary nomenclature indicating the type of board (e.g. TEST, PLATFORM, FLATSAT...)
  • vN.NN is the version number (e.g. v1.2)
  • All files inside a PCB folder must be prefixed with the folder name.