Skip to content

Latest commit

 

History

History
146 lines (129 loc) · 6.98 KB

requirements.md

File metadata and controls

146 lines (129 loc) · 6.98 KB
Raw

Requirements

We have implemented a simple web application called "BadgeApp" that quickly captures self-assertion data, evaluates criteria automatically when it can, and provides badge information. Our emphasis is on keeping the program relatively simple.

This file provides information on the basic high-level requirements of the BadgeApp. Putting them here will hopefully make certain choices clear, and also perhaps eliminate useless repeat arguments. In a few cases we briefly note how we currently meet the requirements.

In this document we'll use the term "open source software" (OSS), and treat Free/Libre and Open Source Software (FLOSS) as a synonym.

High-level requirements

The BadgeApp web application MUST:

  1. Support basic login and editing functionality. The application MUST allow users to sign in/login using GitHub or an email account, create project badge entries, edit those entries (if authorized), and log out. The system MUST calculate and show a project's progress towards getting a badge, and MUST support multiple badge levels with their own criteria. When users edit a badge entry and have JavaScript enabled, the system MUST provide immediate feedback on how their changes are affecting progress towards getting a badge. People MUST NOT be required to log in to see badge entries in the normal case. Admins MUST be able to edit or remove projects (e.g., to deal with spam and false claims).
  2. Meet its own criteria. This implies that it MUST be open source software (OSS). We release the source code under the MIT license, which achieves this.
  3. Be capable of being developed and run using only OSS. This means that all required dependencies MUST be OSS (and we strongly prefer dependencies with OSI-approved licenses). It may run on proprietary software; portability improvements are welcome. It's also fine if it can use proprietary services, as long as it can run without them. See CONTRIBUTING.md for more.
  4. Support modern web browsers. Support users of relatively-modern widely used web browsers, including Chrome, Firefox, Safari, and Internet Explorer version 10 and up. We expect Internet Explorer pre-10 users will use a different browser.
  5. NOT require JavaScript to be enabled. JavaScript MUST NOT be required on the user web browser for basic functions, since some security-conscious people disable JavaScript. Instead, the system MUST support graceful degradation. Many features will work much better if JavaScript is enabled, but the basic functions MUST work without it (e.g., be able to see and edit project entries). Requiring CSS is fine.
  6. Support web browsers on laptops, desktops, and mobile. Users must be supported if they are running web browsers on Linux (Ubuntu, Debian, Fedora, Red Hat Enterprise Linux), Microsoft Windows, or Apple MacOS, Android, and iOS. This implies that it MUST have a responsive design. We expect users will edit information primarily on larger screens, but they need to be able to edit on small screens.
  7. NOT require use of a particular hosting environment or VCS. Here "VCS" means "version control system" (such as git). In particular, the system MUST NOT require that projects or users use either GitHub or git. We do use GitHub and git to develop BadgeApp (that's different).
  8. Automatically fill in some criteria where it can on GitHub projects. Automating filling in data is a never-ending process of refinement. Thus, we intend to fill a few to start, and then add more automation over time. At a minimum we intend to automate projects hosted on GitHub, but we welcome automation for projects hosted elsewhere.
  9. Be secure. See the separate security document for more about security, including its requirements.
  10. Protect users and their privacy. In particular, we MUST comply with the EU General Data Protection Regulation (GDPR). Don't expose user email addresses, and don't expose user activities to unrelated sites (including social media sites) without that user's consent.
  11. Be accessible. We strive to comply with the Web Content Accessibility Guidelines (WCAG 2.0) (especially at the A and AA level).
  12. Support internationalization/localization.
  13. Be reliable. As a matter of policy we require that our test suite have at least 90% statement coverage (in practice we exceed that), the development process MUST use a variety of tools to help detect problems early, and there MUST be a continuous integration platform (to immediately test check-ins).
  14. Perform well. Users avoid slow sites. Our primary pages (front page, login, project list, show or edit project) must perform reasonably well. The front page MUST get to "first interactive" use for a new user in less than 3 seconds on average on a high-speed link (e.g. as measured by https://www.webpagetest.org given Dulles, Virginia as the test location). In practice we achieve much better than this; see the design document discussion about performance.
  15. NOT require a large amount of effort to develop or maintain. We choose systems that easy to develop and maintain in, such as Ruby on Rails, to do this.
  16. Record aggregate statistics. We need these aggregate statistics to monitor the status of the badging project, and focus primarily on projects. These are aggregations, to help preserve user privacy. See /project_stats and /criteria for these statistics.

We do not need to support offline editing of data.

Specific requirements

There are many specific requirements. Instead of having a huge unread requirements document, specific requirements are normally proposed and processed via the GitHub issue tracker. See CONTRIBUTING for more about our process.

See also

Project participation and interface:

Criteria:

  • criteria.md - Criteria for "passing" badge
  • other.md - Criteria for other badges (silver and gold)

Development processes and security: