How to get started in the project

Project Elara is not the work of one person, but the work of a team - and we welcome anyone who wants to work with us to join us. If you’re new to the Project, or interested in participating in it, this part of the Handbook is for you!

If you’re just starting with us, we want to make sure that joining Project Elara is as seamless as possible. And we know it can be quite confusing to start work on any research or open-source project, with bewildering documentation and a lack of a clear beginner’s guide to follow. This is a step-by-step guide to quickly get up to speed and become part of Elara’s mission!

Step 1: Get in touch¶

We want to make sure that you can get in touch with us. This is especially important so that we can explain things and troubleshoot in case you run into any trouble with the onboarding process! If you’re on Discord, you can join our Discord server by copying our server invite link https://discord.gg/Zr37GyxzDd into your web browser. You can also send an email to either one of the addresses below:

• elaraproject.sci@gmail.com, which is our official organization email (this is the recommended email for official inquiries)

• jacky.song.elara@gmail.com, which is the email of Jacky Song, our organization head and chief administrator (this is the recommended email for fast responses)

Step 2: Understand the basic onboarding tasks¶

Before working on the Project, we want to get to know you a little more, and make sure you have access to the main platforms we use below.

New Member Form¶

There is a New Member Form available to anyone who wants to join. We highly recommend filling this out first. This simply is used so that we can get to know you a little more, and we thank you for providing a little bit about yourself!

Sign up for Codeberg¶

Project Elara operates much of its research & development on Codeberg, a repository of all our progress so far. We require that members set up an account so that they have easy access to our work. Start by using the link provided - make sure that you use an email so that you feel comfortable with being publicly-visible. For students, please do not use your school email, and make sure to use an email that you will continue to have access to after graduation. Once you have a Codeberg account, please share your Codeberg username with a Project Elara leader, who will then give you write permissions to our repositories.

Installing Git¶

Git is a tool that we use for collaboration and storing a history of our work, which is immensely useful. We give a short tutorial to using Git at the end of this chapter. If you are unfamiliar with Git, we strongly recommend going through it!

Signing the Licensing Policy¶

Lastly, we have a Licensing Policy that we would like members to look at and sign. This policy exists to protect our values and keep us dedicated to our mission. It helps us know that you are well-committed and understand our policies. For this reason, we require that all incoming members sign it.

Signing the Charter (Optional)¶

All members initially start off as associate members, which means that they have the privileges and rights of membership but do not have voting rights or the ability to take a leadership position in the Project. Associate members can become full members, which do have voting rights and are able to hold leadership positions, but require much more commitment and obligations. We recommend attaining full membership for anyone who deeply believes in the cause and wants to be part of Project Elara for the long-term. This requires only that you sign the Project Charter and therefore vow to abide by and defend it, but is completely optional. If you are interested, feel free to read through the page linked above.

Step 3: Understand our organizational framework¶

Project Elara is a participating organization in RCOS, the Rensselaer Center for Open Source. Whether you are a student currently attending Renssealer Polytechnic Institute (RPI) contributing to the Project for credit, or if you are simply interested in working outside of RCOS, we have a spot for you!

Understand that Project Elara is open to all experience levels - in fact, you don’t even need to have experience working on open-source research or have a strong grasp in the type of work we do. Other than our more hands-on, technical, and mathematical aspects, we are also open to writers, musicians, artists, designers, and other people in creative fields. Regardless of how you want to contribute to the Project and the amount of experience you have, we are more than ready to welcome you, help you settle in, and find work that you enjoy doing.

Step 4: Familiarize yourself with general information about the Project¶

But first, we want to make sure you know what we do, and what our mission is! First, make sure you read our mission statement, which we’ve put down below:

We believe in open science: science without paywalls, done for the sake of advancing scientific knowledge and the public good. And we believe in the value of open source: making our code and hardware public, ensuring that it is available for everyone, so that no one will be able to establish a monopoly for its use.

In terms of the platforms we use, we’ve provided brief descriptions of each below.

As mentioned above, Codeberg is our main platform to coordinate our open-source research and development, hosting our code/designs, holding documentation, tracking tasks, and more. We are also on OpenCollective, where we keep track of our purchases for materials and equipment, ensuring financial transparency. Additionally, we are on Weblate, where we coordinate translations. Lastly, we use Substack for article writing and sharing our personal stories, in the hopes of raising awareness for the Project and also allowing opportunities for members to express themselves creatively.

Last but not least, we believe in working as a team, treating each other with kindness and understanding, and making sure everyone feels comfortable and safe within our team. A big part of this is that we carefully track contributions so everyone gets credit where credit is due. Working with us is contingent upon you affirming these ideals. If you choose to espouse, disseminate, or take action based on ideas that are hostile to our mission, you will not be allowed to further participate in our work. We will trust that you will act in good faith - please do not break that trust.

Optional: Gain a basic understanding of our research¶

We also want to make sure you have a basic grasp of our research and our design! For this, we highly recommend watching our trailer aimed at anyone new to the project.

Reading the first chapter of this Handbook is also recommended, but feel free to skip that if you don’t have the time.

Step 5: Pursue your interests¶

Having read our mission statement and our introductory poster, we want to make sure you have an idea of what we’re working on! Our general projects can be found on our research website. For more specific details on each project, please speak to our other members on the Discord. Feel free to ask questions!

To help divide up our work and to make best use of everyone’s talents, we have divided our team into several divisions (we colloquially just call them “teams”). At the moment, our divisions/teams are, respectively:

• The research team, which focuses on developing the theoretical groundwork of our space-based power system using both analytical calculations and physics simulations. This is an ideal team to work in if you have training in applied math or physics.

• The build team, which focuses on construction and testing of power system prototypes, with plenty of hands-on work!

• The engineering team, which works on creating CAD models, turning designs into buildable prototypes, and all-around engineering tasks

  • There are also specialized groups within engineering that work on a specific area, such as aeronautics/astrodynamics and electronics.

• The software & web development team, which focuses on developing and maintaining our open-source software (and software libraries), documentation, and web content (including our multiple websites). Experience in physics/engineering is a bonus, but not required. If you’re a developer, this might be the place for you!

• The embedded development team, which (as the name suggests) works on embedded systems and microcontrollers for our hardware.

• The media team, which works on communicating and promoting the project through art, video, music, and other mediums, as well as designing our posters, website, and software user interfaces (UIs).

  • This is especially well-suited to anyone with experience or interest in the visual arts (in particular digital art, photography, film production, motion graphics, and graphic design) or music.

• The community & outreach team, which focuses engaging with the community, helping out, and spreading the awareness of Project Elara and encouraging more people to join us. This includes volunteering, fundraising, public speaking/presenting, and seeking out potential partners for Project Elara.

Some of the teams require more technical knowledge than others. A table of the recommended prerequistes for our technical teams is given below:

If you aren’t familiar with these topics but still want to contribute, or if you want a refresher, the good news is that the Handbook allows you to self-learn (or review) nearly all of these topics! It has chapters on all the prerequisite math & physics, embedded development, programming in a variety of languages (as well as web development), and numerical computing to help you get started, among others. It is recommended to spend some time learning the prerequisites prior to working on a specific Elara subproject, but again, we have no minimum skill requirement, and everyone can contribute!

Please also make sure that you let us know how you’d like to keep in touch with us, so that we can work together more easily - again, our work is highly collaborative in nature. Our main platform is Discord and all of our leaders are on Discord, but we can accomodate other platforms. If you try a role and find that you don’t like it, that’s okay! Just let us know, we are happy to help you find something you enjoy doing!

Step 6: Next steps¶

Once you’ve done all the previous steps, you’re all set to start working with us! What to do next depends on which team/division you wish to join. Our leaders are more than happy to guide you through the process.

First, for anyone who wishes to work in the research, embedded, engineering, or build team, we want you to have a basic understanding of the technology we are developing. Hence, we recommend taking a quick look through the Elara laser development, Elara spacecraft, and Elara Labs repositories, as well as the Elara research site. In addition, since we are developing a type of laser called a free-electron laser, there are specific components of the laser that are useful to have some background in. For this, we recommend watching the veritasium video explaining how an electron gun works (between 2:45-3:53 in the video) and the veritasium video explaining how an undulator works (between 21:15-22:10 in the video); both links are timestamped.

We post all of our tasks on our general project tracker. Just let us know which task(s) you’d like to work on by adding a comment under the task(s), or by sending us a message: you can take whichever tasks interest you! In each task, we list out the work description in detail, as well as relevant sections in the Handbook for any background knowledge required. You are also welcome to work on improving this Handbook itself in the Elara Handbook repository!

And as mentioned, please get in touch with us, either by emailing elaraproject.sci@gmail.com or joining our Discord server (via the invite link mentioned previously). We’ll guide you through participating in the community and help you find a way to contribute. We want everyone to have fun and enjoy working in the Project.

Addendum: A short tutorial to Git¶

At Project Elara, we use the open-source version-control system Git for tracking contributions. Effectively, Git acts as a “time machine” for Project Elara, saving “snapshots” of each of our repositories in time, which we can always go back to later. Git can be pretty complex, so here is a list of useful Git commands to use.

General concepts¶

• A repository is any folder that is tracked by Git. Repositories can be local (on your own computer) or remote (online)

  • Another word used for remote is upstream, which comes from the river analogy of a repository - your local repository are located “downstream” from the remote (online) repository, while the remote is “upstream” from your repository

• A commit is a saved change in the repository’s history. Modifying some files, creating new files, or deleting files all qualify as changes.

• A branch is a self-contained version of the repository. A repository can have multiple branches (like branches of a tree) which each contain code/docs/etc. developed in parallel. This is one of the most useful features of Git!

• A merge is when you combine two branches together. This allows the changes from one branch to be added to those in another branch.

• A pull request is a request for a merge. It is frequently used when you want your changes to be reviewed before merging.

• A push is an upload of your local changes to a remote (online) repository. It is only important for repositories that are synchronized with a remote repository.

• Similarly, a pull is a download of changes from a remote repository to your local repository. Again, it is only important for repositories that are synchronized with a remote repository.

Typical Git workflow¶

Note: explanations of each of these commands is given below.

# download online repository
git clone https://your-repository-url.com
cd your-repository

# make some cool changes...

git add <your-changed-files>
# if you are lazy you can instead run:
git add * # this adds all your changes

git commit -m "Description of your changes" # 7 words or less
git pull --no-ff # sync online changes
git status # check everything looks good
git push # upload your changes

Basic commands¶

• git init: This command sets up git to “upgrade” a normal folder into a git repository

• git clone: This command downloads a remote repository onto your computer.

• git status: This command shows the current status of your repository. It is recommended to run this command often and before you run any other Git command since it might help you troubleshoot issues or find issues prior to running a (potentially destructive) command.

• git add path/to/files/or/folders: This command adds files (or non-empty folders) you have modified/created/deleted. You must run this command before you commit anything!

• git rm path/to/files/or/folders: This command deletes files (or non-empty folders) from your repository. It is highly recommended to use this command as opposed to deleting the files from your file manager manually or using the rm command directly, since git rm allows Git to track the change in a more consistent way.

• git commit: This command creates a commit, and opens a default text/code editor to create a commit message with a description (assuming you have run git add beforehand)

  • Important: In the commit message, a short (<7 word) description should be in the first line, the second line should be blank, and a long description should be put in the third line and any following line(s). There is no line limit, but try to keep commit messages wrapped to <15 words per line.

  • Unless you are already experienced with the Linux/Unix commandline, it is not recommended to use this command out of the box since the default editor chosen by git is Vim, which uses nonstandard key-bindings.

  • To alleviate this issue, it is recommended to run git config --global core.editor notepad (to use Windows notepad as the text editor) or git config --global core.editor <your-preferred-editor> on Mac/Linux (substitute <your-preferred-editor with the commandline name of the editor you want to use)

• git commit -m "Your description": This command creates a commit with only a short description, and is recommended for quick changes (or if you are a beginner at Git)

• git commit -s -m "Your description": Same as git commit -m but it adds a signature to the commit. Generally unnecessary, unless you are working on a repository with very specific licensing terms (we recommend this for public domain-licensed repositories)

• git commit --amend: Modifies your most recent commit. You must run git add beforehand to track your changed files!

  • The commit message format is the same as git commit (first line for short description, second line blank, third and all following lines for long description)

  • This suffers the same issue as git commit in that it launches Vim by default, so it is not recommended to use it out of the box

  • It can be fixed the same way (using the git config commands to set the default editor to something else)

• git commit --amend -m "Your revised description": Modifies your most recent commit, with a description. Useful for changing your last commit’s commit message (for instance, if you misspelled a word in it)

• git commit --amend --no-edit: The same as git commit --amend, but it automatically uses the same commit message as your last commit, so you don’t have to re-type the same commit message over again

• git pull: downloads (“pulls”) changes from a remote repository to your local repository.

  • There are also specific versions of this command for different purposes.

  • For instance, git pull --ff-only performs a “clean” pull and tries update your repository without touching your local changes. However, it does not always work!

  • Meanwhile, git pull --no-ff performs a merge and tries to combine your repository with the remote repository’s changes, which can be more “messy”, but works more reliably

  • If neither command works, you have something called a conflict. These are infamously annoying to deal with, and they usually come from too many people editing the same files at once. To fix conflicts, consult this guide

• git push: uploads (“pushes”) changes from your local repository to a synced remote repository.

  • In certain cases, you may want to override the remote repository’s changes with your own. For this, you can run git push -f for a forced push. This is a dangerous action so only do this if you’re sure!

• git log: Shows a list of all changes by all contributors. Use the k key to scroll up, the j key to scroll down, and the q key to quit

  • A prettier version of this command (though not always more useful) is git log --graph --all --pretty --oneline

• git blame path/to/file: Shows which contributors have edited a particular file in the repository

Configuration¶

• git config --list: This command shows all your Git configuration options. Bear in mind that this can be quite long!

• git config --global user.name "Your name": This command sets your name, which will be tracked in your commits. You do not have to use your real name if you are uncomfortable (unless if you are taking the RCOS class, in which case you unfortunately do have to)

• git config --global user.email "your-email@example.com": This command sets your email, which will also be tracked in your commits. If you’re working on a repository synced to a remote repository, be aware that this email will be publicly visible!

  • For Project Elara contributors, this should be the same as your Codeberg account email

• git config --global init.defaultbranch NAME: This command sets the default git branch name for new repositories. In the past, the default name was “master”, but due to its historical connotations, it is recommended to run git config --global init.defaultbranch main to set the default branch name to “main”

Branches¶

• git checkout -b NEW_BRANCH_NAME: This command creates a new branch with the name NEW_BRANCH_NAME (substitute it for your chosen branch name).

• git checkout ANOTHER_BRANCH_NAME: This command switches to another branch with the name ANOTHER_BRANCH_NAME (substitute it for your chosen branch name).

• git branch -a: This command lists all branches

• git branch -m REVISED_BRANCH_NAME: This command renames your current branch to REVISED_BRANCH_NAME (substitute it for your chosen revised branch name)

• git push --set-upstream origin: This command pushes a newly-created branch to the remote (online) repository.

• git merge --no-ff OTHER_BRANCH_NAME: This command merges another branch with the name OTHER_BRANCH_NAME (substitute for the branch’s actual name) to the branch you are currently working on.

  • This is not recommended for use in multi-contributor repositories except in special cases; instead, Codeberg and GitHub have tools to make a pull request, which allows others to review the changes before merging.

• git merge --abort: This command stops a merge; useful if something goes wrong during a merge.

Submodules¶

• A submodule is like a git repository inside another git repository. It is very useful when you want to include code from another git repository and sync the code with that repository

• git submodule update --init --recursive: This command updates all existing submodules. This is important because Git generally does not download submodules by default.

• git submodule add https://your-submodule-url.git: This command adds a new submodule from the online URL https://your-submodule-url.git (obviously replace it with the actual URL of the repository you are using).

  • You can commit a submodule with git add <submodule-path> to track it in your Git history

• To delete a submodule, run git rm <submodule-path> and commit the change. Historically this was much more complicated to do; see this Stack Overflow post for historical instructions, but now it should be much simpler.

Other useful resources¶

• Git TLDR: A quick reference to the most useful git commands. Note that if you go to their main website and enter “git” in the searchbar, they also offer reference pages to other git commands, like these:

  • Git TLDR - commits

  • Git TLDR - branches and branch operations

  • Git TLDR - adding files

  • Git TLDR - deleting files

  • Git TLDR - submodules

  • Git TLDR - merging

• Git unofficial tutorial - this one is particularly to-the-point and (IMO) entertaining in its presentation. There are also other less entertaining but useful tutorials listed below:

  • Git crash course

  • Git’s official tutorial

• Git cheatsheet by GitHub

• Advanced Git guide