/spec

Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
Raw Blame History
201 lines (114 sloc) 9.94 KB

Contributing Guidelines

🌟 Thank you for contributing to DLx! 🌟

Below is some information on how you can contribute to the DLx data format project, whatever your level of technical expertise.

Quick Links

Open an Issue | User Documentation | Pull Requests | DLx Contributing Guidelines | Code of Conduct

Contents

General Guidelines for DLx Projects

Here are some general guidelines that apply to all DLx projects:

Questions?

Check out the user documentation.

You can also ask a question by opening an issue in this repository.

Reporting Bugs & Other Issues

Found a problem in the specification? Open an issue on GitHub describing the problem and its severity. Does the issue affect just a single schema, or several schemas? Does the issue have the potential to cause errors in applications using data in this format? Include as much detail as possible.

Suggesting Features

Have a feature you'd like to suggest? The project would especially benefit from the following types of suggestions (other suggestions are fine too):

  • Is there some part of the specification that could be structured more simply, without losing any information?

  • Is there a use case, property, or other piece of information that linguists commonly use that hasn't been included in the specification?

  • Are there any parts of the specification that are unclear or could be made clearer?

  • Is there a type of linguistic object or data that isn't included in the specification?

  • Can the documentation be improved?

To suggest a feature, simply open an issue in the GitHub repository for this project, and explain your suggestion. If you are able, consider providing an example in JSON of how your suggestion would work, and if possible a valid JSON Schema describing the new format.

If you're suggesting an improvement to the documentation, please include the original wording and how you would change it, or at least a short description of what needs to be changed.

When suggesting a feature, think about whether this would require a major, minor, or patch update to the specification (following semantic versioning principles), and include that in the comments for your issue.

Contributing Code / Changes to the Schemas

If you'd like to contribute changes to the code or the schemas in the repository, follow these steps:

  1. Open an issue with information about the feature, fix, or change you'd like to make. Follow the guidelines in the Suggesting Features section above.

    Note: It is a good idea to wait until your suggested change is approved by a maintainer before writing any code.

  2. Fork the repository and clone it to your computer.

  3. Create an issue branch for the particular issue you are addressing. You should only make changes to the code that are directly relevant to this issue.

  4. (Optional) Open a pull request to track your changes as you work. The pull request will have a simplified version of this checklist that you can follow while working on your code. You will need to make at least one small change before you can open a pull request.

  5. Set up your development environment by installing Node.js. Use the latest LTS release.

  6. Install project dependencies by running npm install in the project folder from the command line.

  7. Update project dependencies by running npm outdated in the project folder from the command line.

  8. Update the documentation (README.md, CONTRIBUTING.md) to reflect the changes you plan to make.

  9. Write or update tests for the changes you are going to make.

    • Make sure that your tests fail before writing other code.

    • The tests are located in the /test folder. The file schemas.test.js checks that all the example data in the schemas is valid against its schema. Other tests only need to be added to check for issues that cannot be checked using the example data. Example data can be added or updated as necessary.

    • Tests are run using Jasmine for Node.js. See the Jasmine documentation for Node.js for more information on how to write tests in Jasmine.

    • The tests use the ajv library to validate the schemas against the JSON Schema format, and validate the sample data against the DLx schema. See the ajv documentation for more information on how to use this library to validate schemas.

    • Schemas do not have to be tested against invalid sample data, unless testing for specific issues that have arisen in the past, or common errors that developers are likely to make.

  10. Make changes to the schema(s).

    • The schemas are located in schemas/yaml. Do not update the schemas in schemas/json, or your changes will be overwritten.

    • The schemas use the JSON Schema format to describe how data should be structured. See the latest version of the JSON Schema for more details.

    • Update the "description" field of any schemas that you change, as needed.

    • Increment the version number of any schemas that you update, following semantic versioning.

      • major: When the schema is changed in a way that makes it incompatible with previous versions

      • minor: When new properties are added, or optional properties removed, or other changes are made to the schema that are backwards-compatible

      • patch: Typos, changes to descriptions, minor bugs and hotfixes, or other changes that do not address the functionality of the schema

  11. Increment the versions of affected schemas if you didn't in the last step

  12. Run the tests using npm test in the command line. Fix any issues that arise. If you find an issue that is unrelated to the one you are working on, open a new issue for it.

  13. Double-check the documentation (README.md, CONTRIBUTING.md) to make sure it still reflects the changes you made.

  14. Get the latest changes from the master branch and resolve any conflicts that arise. Run the tests again.

  15. Run the build script by running npm run build from the command line. This does the following steps for you automatically:

    1. Generate the JSON versions of the schemas (npm run convert)

    2. Regenerate the documentation website (npm run docs)

    3. Run the tests again (npm run test)

  16. Check the documentation for the changes you made (/docs)

  17. Open a pull request from your issue branch into the master branch of the DLx repository. See GitHub's advice on How to write the perfect pull request.

    • While working on your pull request, you should write [ci skip] in each of your commit messages to skip automated testing, until you are ready to test your code.

  18. Address any changes requested by the reviewer

  19. Wait for a maintainer to merge your changes

These steps are for maintainers only:

  1. Write the release note for the pull request

  2. Squash & merge the PR into the master branch

    • Title: LABEL: description (#000)

    • Description

    • Changelog: LABEL: description (closes #000)

      • CHANGE: (breaking) changes
      • DEP: changes to dependencies
      • DEV: changes to development environment
      • DOCS: changes to docs
      • FIX: bug fixes
      • IMPROVE: code enhancements
      • NEW: new features
      • REMOVE: removed features
      • TEST: changes to tests

  3. Increment the version number of the master branch by running npm version {major|minor|patch} from the command line, and commit the change. Do not include a commit message (it will default to the version number instead).

  4. Create a GitHub release when the necessary features are ready. This will trigger Travis CI to run the upload script and publish to npm.

    • Title: vX.X.X

    • Description: High-level overview of the changes

    • Changelog:

      • List the changes for each schema separately under its own heading. General project changes get their own heading as well.

      • LABEL: description (#000)

    • Compile the list of changes from each of the commits on the master branch

  5. Write a blog post about the changes (for major/minor updates only)

Branching Model

This project uses the following branching model:

  • The master branch is always production-ready

  • Each issue receives its own branch

  • Each issue branch is tested thoroughly and must be production-ready before being merged

  • Issue branches are merged directly into the master branch

  • The master branch is periodically tagged for a release and GitHub release notes made, and the code published to npm at that point

  • Releases are managed using GitHub milestones to track when all the relevant issues are completed, and the master branch is ready for publishing on npm

(If development needs to happen simultaneously on minor changes / hotfixes and major breaking changes, it may be necessary to switch to a release branch model.)