Software Development Process

Submitting Issues

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

Using the Project Board

We use a GitHub Kanban-style project board to organize and track issues being worked on.

• New issues are automatically added to the "For consideration" column.
• Once an issue has been reviewed and spec'd -- usually by the core team -- it is moved to the "To do" column.
• A developer might choose to work on it, moving it to the "In progress" column.
• Once the code is tested and ready, and a Pull Request (PR) has been created 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".

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 Issues

Issues in the "To do" column are available to be selected by developers and worked on. 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.

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

Follow Code Styleguides and Prevailing Style

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 Unit Tests

In React: Currently, we have the most minimal setup for unit tests in React. Moving forward, we will need to expand it according to this Issue's details: https://github.com/internetarchive/iaux/issues/226 Please ping us if you are excited to help us get to a better testing ecosystem around our React components.

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 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.

Formulate 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 the development task is code complete and it is time to create a Pull Request (PR), 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 expected action by the PR author. Consider this the beginning of a dialogue. Remember that PR's 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

Anyone is welcome to review and provide feedback on PR's. However, in order to be accepted into master, each PR must be reviewed by and receive the approval of a core committer, generally one who is familiar with the part of the code base that will be impacted by the PR.

Code reviewer responsibilities:

• Verifying code style and best practices
• Verifying software design decisions
• Suggesting alternative solutions
• Ensuring code meets all issue requirements
• Preventing typos
• Encouraging testing of new/modified code

When leaving comments in the code, generally prefix the comment with one of the labels below, listed with its meaning, in order to make clear what action the developer is expected to take:

• COMMENT: An idea or thought directly or indirectly related to the current code. The PR author must read the comment but does not need to act on it.
• SUGGESTION: A specific suggestion of a solution or a diagnosis of a problem. The PR author must read and consider the suggestion, and should attempt to resolve the reviewer's concern by doing one of the following:
  • Making the suggested change
  • Making a different change to solve the problem
  • Doing nothing and explaining why they did so
• BLOCKER: An issue that the reviewer is convinced will cause significant problems now or in the future. The PR author must read and address the issue, though they do not have to follow the reviewer's suggested solution exactly.
• QUESTION: A question that has arisen for the reviewer, which, when answered by the PR author, might lead to subsequent feedback using any of the previous labels.

E.g.

SUGGESTION: Use a clearer, less obscure variable name. Favor readability over brevity.

Generally, once code has been reviewed, the PR author should consider each point of feedback, take any needed action, and then resolve the comment in GitHub. If the author feels additional review is needed, they can request it.

Accepting Pull Requests

As noted above, generally a core committer is needed to grant final approval to the PR and accept it into master. From that point, the code will generally be pulled by a core team member into the Archive.org codebase and subsequently deployed.