Skip to content

Software Development Process

Jump to bottom Edit New page
Brenton Cheng edited this page Apr 26, 2019 · 10 revisions

Submitting Issues

When submitting issues in GitHub, choose an appropriate issue type and fill out the corresponding template. Be as complete as you can.

Picking Issues and Using the Project Board

We use a GitHub Kanban-style project board to organize and track issues being worked on. Issues that are in the "To do" column are available to be selected by developers. If you feel interested in and qualified to work on an issue in this column, assign it to yourself and drag it into the "In progress" column.

Once the code is tested and ready, and you've created a Pull Request (PR) for it, the issue can be moved to the "Code review" column, where it will be reviewed by the community, as well as core committers. Additional changes may be required. Once a core committer approves the PR and merges it to the master branch, the issue can be moved to "Done".

Newly created issues appear in the "For consideration" column and will be spec'd and reviewed by the core team before being moved to "To do".

Issues may have any number of labels attached to them. See the reference list of labels.

For a higher-level view of our priorities, see the roadmap.

Picking a First Issue

If you are a new contributor to this project, consider picking issues labeled as Good First Issue or Easy.

Development Tips

Work in a Feature Branch

We generally follow GitHub flow for our development process. You'll want to fork the IAUX repo; make changes in your own local feature branch and push them to your fork; and then when ready, create a Pull Request back to the original IAUX repo.

When naming branches, prefix the name with the GitHub issue number and a hyphen to facilitate branch auto-completion. E.g.

123-refactor-music-links

Code Style and Styleguides

Please adhere to stated styleguides. e.g. We follow the AirBNB styleguide for Javascript. One of the easiest ways to remain compliant is to use an automated linter in your code editor.

Where no styleguide is explicitly stated, follow the prevailing style in an existing file or ask a core committer or the community when creating a new file.

Write Automated Tests

Good automated tests are part of good code. We encourage Test-Driven Design (TDD), whether or not tests are written first. i.e. When designing new code, make sure that you are doing so in a such a way that the code will be easy to test.

We use unit tests (using jest) to ensure that the individual parts are working and integration tests (using Puppeteer) to ensure that the parts work together correctly.

Whenever a bug is found, the first thing we do is write a regression test that would have caught that bug, making sure the test fails, and then we implement the bug fix, making sure the test now succeeds.

Write Excellent Commit Messages

When writing commit messages, obey these standard guidelines:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Creating Pull Requests

When creating Pull Requests (PR's), fill out the auto-generated template as completely as you can. This will increase the chances of having your PR accepted.

After receiving feedback from the community and/or core committers, it is likely that changes will be requested. See the Reviewing Pull Requests section for the prefixes we use to indicate the "strength" of the requests. Consider this the beginning of a dialogue. Remember that Pull Requests and code are not personal. We are all working toward the common goal of creating fantastic user experiences built on a well-structured, maintainable code base.

If you decide to challenge a reviewer's suggestion, clearly state your reasons. Core committers have the authority to help resolve any impasses and keep the process rolling forward.

Reviewing Pull Requests

Typically...

TODO: Remaining topics to cover:

  • Development tips
    • Using Git/GitHub: using feature branches, branch names, commit messages
  • Creating Pull Requests: use of PR template, author responsibilities
  • Reviewing Pull Requests: giving feedback, reviewer responsibilities
  • Issue resolution: what happens next, integration with Archive.org code base
Add a custom footer
Clone this wiki locally