search

jsonresume / resume-schema

JSON-Schema is used here to define and validate our proposed resume json
http://jsonresume.org
MIT License
2.09k stars 278 forks source link

Maintenance: Cleanup #349

Open evanplaice opened 4 years ago

evanplaice commented 4 years ago

Most of the maintenance work (adding tests, updating deps) is complete. The following outlines the rest. Feedback is welcome.

Note: The actual removal of validator.js and its export will be handled under 1.0 release planning

antialias commented 4 years ago

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?

evanplaice commented 4 years ago

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.

antialias commented 4 years ago

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?

antialias commented 4 years ago

PTAL: https://github.com/jsonresume/resume-cli/pull/354

antialias commented 4 years ago

PTAL: https://github.com/jsonresume/resume-schema/pull/365

antialias commented 4 years ago

PTAL: https://github.com/jsonresume/resume-schema/pull/361

antialias commented 4 years ago

PTAL: https://github.com/jsonresume/resume-schema/pull/363

antialias commented 4 years ago

revise the contents to follow the KeepAChangelog format

any thoughts about using something like committizen to manage either of these:?

evanplaice commented 4 years ago

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

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.

antialias commented 4 years ago

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.

evanplaice commented 4 years ago

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.