contributor workflow

tl;dr

SETUP

1. fork our repo
2. clone your fork git clone https://github.com/[YOUR_USER_NAME]/netnet.studio.git
3. cd into the repo cd netnet.studio
4. run the setup script npm run setup

• this script will add a remote upstream if you let it, if not you'll need to git remote add upstream https://github.com/netizenorg/netnet.studio.git yourself.

5. run the server npm run start

DEVELOPMENT

1. create a "feature" branch git checkout -b [FEATURE-NAME] (if necessary git pull upstream main to pull updates)
2. work locally, ensuring you're conforming to our coding style npm run lint while making commits to the new feature branch and occaisonally/eventually pushing to your fork git push origin [FEATURE-NAME]
3. Create a PR from your feature branch to our main branch.
4. Once your PR has been merged, clean things up before starting on your next feature

git checkout main
git pull upstream main
git push origin --delete [FEATURE-NAME]
git branch --delete [FEATURE-NAME]

---

setup a local development environment

netnet.studio is almost entirely a client-side application, but there is some server side logic. For this reason we need to have nodejs installed (to get things setup and run the server) as well as git. Assuming you have both installed, you can setup a local development environment in a couple easy steps:

1. First, fork the netnet.studio repo and then clone it to your local computer (replacing "YOUR_USER_NAME" in the git URL below with your own)

git clone https://github.com/YOUR_USER_NAME/netnet.studio.git

2. Then you'll need to cd (change directory) into the netnet.studio folder and run our setup script.

cd netnet.studio
npm run setup

The setup script will guide you through a series of questions and handle the entire setup for you. You don't need to answer all of the questions the first time around you can always rerun the setup script later to return to any questions you skipped. We love setup scripts because they help lower the barrier to entry for contributors, but they can also (unintentionally) obfuscate the process. For that reason we've also put together document ion for how to setup a local environment manually if you're curious.

running netnet locally

Assuming you still have a terminal open to the repo's directory, simply run:

npm run start

Then visit http://localhost:8001 in the browser (assuming you haven't changed the default port number in the .env file from 8001 to something else).

making contributions

setup a feature branch

Before you start working on a new feature or bug fix ensure you're working with the latest version of netnet.studio by pulling updates from our main branch

git pull upstream main

If that failed, make sure you setup our repo as your remote "upstream" by running git remote -v, if you didn't setup a remote upstream during the setup you will need to do this manually by running git remote add upstream https://github.com/netizenorg/netnet.studio.git

Create a "feature branch" for the feature/bugfix/etc you plan on working on by running the command below (replacing [FEATURE-NAME] with name for this feature/task)

git checkout -b [FEATURE-NAME]

make sure you conform to the style guide

We're using standardJS as our style guide, so before commuting/pushing any code you should check that everything's tidy by running:

npm run lint

But that can get annoying, so it's better to just install a standard plugin for your preferred code editor. This way we do our linting as we code and don't have to worry about running this command and then going through all the required changes in order to conform to the style guide after the fact.

When writing any CSS, we're doing our best to stick to BEM, refer to this post on CSS-Tricks for a general introduction.

commit and push your changes

Commit significant changes to your feature branch as you work (ensuring you don't have any linting errors or bugs in your console first):

git commit -m "a brief but useful message"

Push your changes to your fork:

git push origin main

create a PR (pull request)

When you're finished create a PR (pull request) from the feature branch of your form into the main branch of the class repo. The arrow icon in the GitHub PR interface between the two repos being merged conveys the direction of the pull request. NOTE: If you don't see your fork in the the drop-down menus, you may first need to click on the "compare across forks" link in the PR page

We may start a "review" for your PR before merging it. If we do give you some feedback or request some changes, the PR will remain open during the review and any future commits you push will automatically be registered in the PR page. Once everything looks good we'll accept your PR and merge your changes with our repo.

post-merge clean up

Once your PR has been merged, clean things up before starting on your next feature. Check out your main branch and pull the changes we merged from your (and any one else's) PRs:

git checkout main
git pull upstream main

Then delete the feature branch from your remote and local repos:

git push origin --delete [FEATURE-NAME]
git branch --delete [FEATURE-NAME]

updating dependencies

There are a few dependencies that we (@netizenorg) or Nick (@nbriz) maintain in separate repos, most important of which is netnet's code editor which is an instance of netizen's netitor. When updates are pushed to these separate repos you'll need to update your local copy of these modules. The following npm scripts can be used to update these dependencies:

• to update the netitor run npm run update-netitor
• to update Color.js run npm run update-color
• to update Maths.js run npm run update-maths
• to update Averigua.js run npm run update-averigua
• to update FileUploader run npm run update-dev

When in doubt, you can always delete your entire node_modules folder and simply run npm install to download a fresh copy of all the dependencies (including 3rd party server side dependencies, listed in our package.json).