resume-schema
resume-schema copied to clipboard
jsonresume
Maintenance: Cleanup
Most of the maintenance work (adding tests, updating deps) is complete. The following outlines the rest. Feedback is welcome.
- [ ] move the changelog
- backfill missing version tags
- backfill release logs
- relocate the changelog contents to CHANGELOG.md
- revise the contents to follow the KeepAChangelog format
- [x] remove redundant/unused code in
validator.js#349- delete the redundant schema import
- remove
pathandfsimports that are non longer necessary
- [x] cleanup the samples #363
- mv
/examples/valid/complete.json->/sample.resume.json - delete the rest,
test/__test__already contains a complete set of test fixtures - remove
resume.jsonfrom pkg.files - add sample.resume.json to pkg.files
- reference the schema in the sample #334
- mv
- [x] clean up
README.md#361- remove mention of
migration.jssince that doesn't exist - make the contents more user-friendly
- remove mention of
- [x] delete
schema.json.html? #365- does this file serve a purpose?
- [ ] CI/CD using GitHub Actions #359 #367 #369
- add CI checks to test every push * pull_request
- add CD to auto-publish to NPM
- remove Travis-CI
- add CONTRIBUTING.md
- [x] migrate validation to
resume-cli- remove documentation from
README.md
- remove documentation from
Note: The actual removal of validator.js and its export will be handled under 1.0 release planning
- [ ] fix
pkg.license- the
licensefield ofpackage.jsonshows the wrong license type
- the
move the validator to a separate resume-validator repo
Perhaps validator.js can be deleted? It appears to proxy directly to an instance of ZSchema.
i.e. stat in the readme that the schema is in ZSchema format and be done with it?
The validator is being moved to the resume-validator repo.
First, so it can be proxied here to prevent a breaking change in the pre-1.0 release. Second, so it can be used in the CLI.
The resume-validator hardcodes the resume schma and it'll enable a couple of useful settings to provide better DX.
Agreed that the validator code does not belong in the schema repo.
I did some work on the validator in my fork of resume-cli; it uses
z-schema-errors to format the errors into human-readable strings.
What are the other use cases for a validator that wraps z-schema outside of running it in resume-cli?
revise the contents to follow the KeepAChangelog format
any thoughts about using something like committizen to manage either of these:?
- ensure that commits are categorized correctly.
- determine wether patch, minor, or major should be used when incrementing the version string.
I have used semantic-release (ie uses the same Angular commit conventions) in the past and prefer not to use that on public projects because it puts the onus of versioning and categorizing commits on contributors. It works well for internal teams where contributors and contributions are regular and constant. Not so much for OSS projects where most contributions are one-off PRs from contributors.
Now that auto-tagging and CD auto-publish is setup, any maintainer w/ push access can bump the version using the 'npm version' command. It...
- runs the tests locally
- increments the version in
package.json - tags the commit with a version number
- pushes both the commit and corresponding tag
- verifies the tests pass on both Node 10 & Node 12
- publishes the change
There is nothing extra to maintain; the process is fully integrated using GitHub Actions. Maintainers don't have to bother policing commit naming conventions, and contributors don't have to care about the versioning strategy. Low effort, low maintenance; ideal for a public project that doesn't change frequently.
Okay, just trying to help bring order here :) Also, big congrats on getting github workflows set up to publish. That's a huge win for getting this project back on track!
I have more to say on the topic though, if you would like to keep reading:
it puts the onus of versioning and categorizing commits on contributors
The onus is on whoever reviews the PR, and github checks can help automate this:
https://github.com/marketplace?category=free&query=commit+message
forcing "squash and merge" can also help with this; only one commit per PR leaves only one commit message to check.
using the 'npm version' command. It...
We might want to consider moving those preversion and postversion scripts into travis though. Publishing is most reliable when run from a consistent environment that is gets nuked and re-built on every run.
contributors don't have to care about the versioning strategy
The versioning strategy is always semver if you're publishing to npm, and someone needs to be able to make an informed decision about when to declare patch, minor, or major; commit messages are a great way to signal this.
There will be a CONTRIBUTING.md that explains the version bump strategy, in short it's a maintainer-only concern. The process is already entirely automated w/ one command.
As for the pre-checks, check the release workflow. The version only bumps if preversion passes. It only gets published if preversion passes on both Node 10 & 12. In the -- extremely rare -- event that local passes and remote fails, it's relatively easy to roll the change back.
The README.md tags will be updated as well to reflect the GH Actions status for both latest and release.
There's a method to my madness. I'm democratizing access by removing any/all ties that require external permissions (ex Travis, NPM). I just modified the theoretical 'Bus Factor' from 1 to infinity; where infinity is any Dev granted 'Maintainer' access.
Ideally, maintainers should have experience with both the schema and implementing templates. As you've seen, drive-by contributors have a tendency to add a lot of extras. It may seem gatekeepy but -- speaking from experience (ie implementing multiple templates) -- any change to the schema will be painful for template makers.