Home

Awesome

Starfish

GitHub version GitHub Open Source Love svg1

As of July 2023, this project is no longer being actively maintained by Indeed. We are immensely grateful for all the support and contributions from our community throughout the years.

While this repository will remain open and accessible, we will not be issuing updates, accepting pull requests, or addressing issues. It is crucial for users to know that the codebase will not receive security updates or patches. Thus, please use this project with caution as it might not be secure or up-to-date with the latest industry standards.

We encourage the open-source community to fork this project if continued development is desired. We hope that the project has been of use and will continue to be valuable in its current state.

Thank you once again for your support and understanding.

Because Your Open Source Contributors Are Stars!

<p align="left"> <img src="img/Indeed_OS_starfish_logo.png" alt="Starfish logo - Light blue circle with gold starfish in the middle and the link to github directory in the top right corner (github.com/indeedeng/starfish) " width="250" height="250" title = "Starfish logo"/> </p> <br>

This is a tool to:

Starfish gives you the option of either using the default settings or making customizations.

Purpose

The purpose of this tool is to make it easy for you to run your own FOSS Contributor Fund

Creating a FOSS contributor fund at your company is a great way to help sustain the open source software your company depends on!

FOSS Funds are democratized - anyone who has contributed to open source in a given cycle gets to vote that cycle for the project they are excited about.
You can use Starfish to determine which of your employees are eligible to vote within a specific time range.

For More Info on what a FOSS Contributor Fund is, and how to start your own, Watch This Talk from FOSDEM or Read This Post on Indeed's Engineering Blog or This awesome article from Open Collective

Getting Started

Prerequisites

First, clone the repo to your computer, then navigate to the starfish folder and run npm ci.

Next, make a .csv file with the GitHub Ids you're interested in checking, and, if desired, an "alternate id" to go with each

Q&A Time!

What do you mean "alternate id"?

I mean, if you normally identify your employees by some unique identifier- like an LDAP, their email, an employee id number, or even just their names- you can add that to the CSV so that your output is more useful to you. (For example, we find a list of the emails of every employee who's eligible to vote in the FOSS Fund that month to be really useful.)
If you decide not to use an 'alternate id', your list of eligible employees will just be a list of their GitHub ids.

Why CSV?

We found that an easy way to get GitHub ids from Indeed employees was through a Google form that automatically recorded their Indeed email. From that form, we got a Google Sheet with employee info that is easily exported as a CSV file. (Go to File, Download As, and then choose CSV.)

How do I make a CSV?

A CSV is just a file of comma-separated values, with a newline between each line. It looks like this:
My GitHub ID is:,Email Address
danisyellis,dgellis@indeed.com
octocat,octocat@github.com
thisNameWillThrowAnErrorBecauseItIsNotARealGithubId,fakePerson@example.com

(Not all CSVs have a header, but Starfish does expect the first row of your CSV to be a header.)
You can create a CSV on your own by creating a file, giving it the file extension .csv, and making it look like the above example. Or, even if you're not using google forms to gather GitHub ids, you can still enter your data into a google sheet (one column per data field, one row per person) and download a CSV from that.

You may want to store multiple CSV files in a folder that's inside of Starfish, but not tracked by git, so we have set up ./CSVsToParse for you.

Then, get yourself GitHub authentication credentials.

Log in to GitHub and register a new personal access token (you can find this under Profile > Settings > Developer Settings > Personal access token > "Generate new token"). Fill the "Note" field with e.g. "Starfish" or another description. You don't need to select any scopes. (By default, a token is allowed read-only access to public information, and that's all Starfish needs). Click "Generate token". Copy the access token and store it as you will need it for the next step.

Next, Create a file named .env, copy the contents of the .env.template file into it, and add your values to the new file.

Time zones

The TIMEZONE value must be one of the following:

If for some reason you want the time to be a constant offset from UTC, you can say : "Etc/GMT+6", to mean UTC-0600. Note that positive values in the TIMEZONE string will result in negative UTC offsets (that is, West of UTC), while negative values will result in positive UTC offsets. This behavior is defined by IANA, not by us.

For example:

TIMEZONE=“Etc/GMT+6”

would output:


Users that contributed between December 1, 2020, 12:00 AM GMT-6 and December 15, 2020, 11:59 PM GMT-6

For further reading see the luxon time zone documentation and the List of tz values

To run:

In your terminal, type node index.js {date1} {date2} {path/to/CSVfile}.csv

In the above, any text inside of curly brackets {} means that you should put your own value in.
Dates should be written in ISO-8601 format. For example, April 1, 2019 should be entered as 2019-04-01.
Here's an example of what the terminal command could look like (I name my CSV files by date): node index.js 2020-10-01 2020-11-01 CSVsToParse/2020-11-01.csv

Tip: You can redirect the output to a file, if you like: node index.js {date1} {date2} {path/to/CSVfile} > {nameOfFileToCreate}.txt

Updating

From time to time, we'll be updating the Starfish code. You can get the newest code with git pull origin main. Just be sure to run npm ci when you do that, in case any node packages were updated.

Other Important Info

Changelog and Troubleshooting

Changelog

We recently created a Changelog over in Starfish's Discussions. If you're using Starfish, I'd recommend Subscribing to notifications for the Changelog. We'll be posting there when big changes happen like interesting new features and, most importantly, when security issues arise and get patched.

Troubleshooting

Contributing

Always feel free to help out! Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

Code of Conduct

Starfish is governed by the Contributor Covenant v 1.4.1.

License

Starfish is licensed under the Apache 2 License.

Maintainers

danisyellis and the rest of the Indeed Open Source team

<p align="center"> <img src="img/OS-gold-starfish-banner.png" alt="Banner of five cartoony gold-colored starfishes arranged like Olympic circles, but with some spacing between, on a background of water" width="596" height="255" title = "Gold Starfish Banner"/> </p>