Skip to content

Latest commit

 

History

History
78 lines (61 loc) · 4.03 KB

disclaimer.md

File metadata and controls

78 lines (61 loc) · 4.03 KB
Raw

[SOME] project disclaimer

What is it?

Typical recommendations list for open source project release preparation.

Issues was found during static code analysis tools with extended rule set. To detect founded issues automatically in project was added the corresponding rule set. For triggered rules was collected and commented all unique issue types.

Described issues and recommendations should not be fixed mandatory(in any way), and does not guarantee the success. This is additional information for decision making process.

The most useful part is in the code analysis tools configuration. Any linter rules can be used as code style guide because it's maintained by community of programmers.

  • package.json - the scripts section
  • .cspell-dict-exclude.txt
  • .cspell.json
  • .eslintrc.js
  • tsconfig.eslint.json
  • .vscode\settings.json

The full issues list is in the log folder: cspell.log, eslint.log, tslint.log

What to do next?

  1. collect issues with npm run lint:* > log/*.log commands
  2. filter log files with linters.sh example commands
  3. repeat collecting after git checkout to some one year ago commit
  4. introduce team with issues, collect feedback, discuss the typical issues and issues resolving methods
  5. find additional info in similar project or communities for issues, that cannot be approved by all team members
  6. make a task list and calculate estimation time to resolve that tasks
  7. make a plan to resolve issues by types using severity or estimation
    • Milestone 1
    • Milestone 2
    • Milestone 3
  8. mark next milestone issue types(eslint rules) as error or warn in the .eslintrc.js
    • rules, that can be resolved in short time mark as error
    • rules, that require long estimation time to resolve mark as warn
    • after resolving all detected by single rule issues mark as error.
    • modify/add the eslint --fix command/script. For that you can make separate .eslintrc.fix.js only with rules in error state
  9. resolve issues
  10. celebrate the milestone termination

Common recommendations

Severity: High

  1. Cover all code units(files, modules, functions, etc) with tests. Collaboration is very hard without unit testing, especially with external teams.
  2. License information: LICENSE.md
  3. License checker
  4. Add contributors list
  5. Add contribution guide, issue & PR templates
  6. Add project goals
  7. Add use cases

Severity: moderate

  1. Use unit test code coverage calculation tools: codecov, coveralls
  2. Add real data calculation conditions:
    • hardware(CPU, RAM, STORAGE)
    • OS architecture(32/64/...) and version
    • browser version
    • input and output data size and type
    • expectable overall calculation time in described conditions(1Tb animal pictures data for the 1 hour using win10x64/Chrome 84/core i7x4/8GB ram)
  3. Add CI/CD configuration: gitlab, Bitbucket, GitHub
  4. Use code quality tools: sonarcloud, code inspector, codeclimate

Severity: low

  1. Follow the preparation checklist
  2. Follow README best practices
  3. Add code style guide
  4. Add live example on stackblitz, gitlab pages, github pages, heroku
  5. Add screenshots
  6. Add link to KB/docs
  7. Add svg badges
  8. Exclude(comment with TODO or disable) fake tests to reduce testing time