Home

Welcome to the NetCreate wiki!

Currently we have:

• Installation Guide is work-in-progress "how to install and run the project".
• User Guide has everyday use instructions for researchers.
• Technical Researcher Guide has information about how to make code-based changes, including logging.
• Decision Log describes, at a high level, the reasons behind our technical decisions because this is interesting stuff to share with other generalist programmers who are learning Javascript web app development.

---

Developer Read Me

If you are contributing code, we ask that you familiarize yourself with our standard practices, a modified GitHub flow approach (which itself is based on git-flow):

1. Use Issues to report bugs, feature requests

Any bugs, code issues, things that people are going to fix (e.g. css) should probably be initially created as an Issue in the repo. This way:

• all bugs and issues are public and we can all discuss them
• they are centralized on the repo

Trello can still be useful for some task management, but ideally anything with content is kept in Issues with the repo for future reference.

2. Assign yourself to any Issue you're working on

Anyone working on the issue should assign themselves to it. This will prevent other folks from working on the same thing.

3. The master branch is always deployable

The master branch should be production-ready, but will usually not have the latest features. In general, this is what should be deployed in the classroom (though during a classroom study sometimes hotfixes might end up in the dev branch). Stable versions will be tagged with a version number, e.g. 1.0.1.

4. The dev branch should be stable

In general, the dev branch should always be a relatively stable running version good enough for QA. Any bleeding edge features are added in separate branches off of dev and merged back in when they are stable.

The rationale is that we want to make sure there are always at least two working branches, especially during a study/enactment. This way, if the master branch is not working, you can fall back to a previous version.

There can be major branches off of dev, for example, if you're trying a whole slew of experimental features for a Fall enactment, you could branch dev-fall-2020 off of dev, and all of your feature branches to that.

5. New Features should be developed on their own branch

When you work, always work on a branch, never directly on dev or master.

When your feature is completed and accepted via the Pull Request, the branch can be deleted.

6. New Features should be merged into dev via a Pull Request

Pull Requests are recommended because:

• They encourage you to document the feature you are adding.
• They provide a natural public place for discussion and review of a series of commits

7. Use npm ci -- Do NOT commit package-lock.json.

Three important points here:

1. Use npm ci -- In general, when packages are added to the system by other developers, you would run npm ci to update your packages. npm ci reads these dependencies from package-lock.json. Use npm ci and NOT npm install.

2. Never run npm install unless you've added a new npm package yourself, or you've been explicitly told to.
   npm install will update dependencies, changing package-lock.json and potentially change module versions and dependency stability.

3. Never commit package-lock.json unless you've added a new npm package yourself and know what you're doing. package-lock.json is intended to lock down our dependency tree and provide stability for the system. It should only rarely be changed.