diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 00000000..192e849d --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,100 @@ +version: 2 +jobs: + build: + docker: + - image: martinthomson/i-d-template:latest + working_directory: ~/draft + + steps: + - run: + name: "Print Configuration" + command: | + xml2rfc --version + gem list -q kramdown-rfc2629 + echo -n 'mmark '; mmark --version + + - restore_cache: + name: "Restoring cache - Git" + keys: + - v2-cache-git-{{ .Branch }}-{{ .Revision }} + - v2-cache-git-{{ .Branch }} + - v2-cache-git- + + - restore_cache: + name: "Restoring cache - References" + keys: + - v1-cache-references-{{ epoch }} + - v1-cache-references- + + # Workaround for https://discuss.circleci.com/t/22437 + - run: + name: Tag Checkout + command: | + if [ -n "$CIRCLE_TAG" ] && [ -d .git ]; then + remote=$(echo "$CIRCLE_REPOSITORY_URL" | \ + sed -e 's,/^git.github.com:,https://github.com/,') + git fetch -f "$remote" "refs/tags/$CIRCLE_TAG:refs/tags/$CIRCLE_TAG" || \ + (echo 'Removing .git cache for tag build'; rm -rf .git) + fi + + - checkout + + # Build txt and html versions of drafts + - run: + name: "Build Drafts" + command: "make 'CLONE_ARGS=--reference ~/git-reference'" + + # Update editor's copy on gh-pages + - run: + name: "Update GitHub Pages" + command: | + if [ "${CIRCLE_TAG#draft-}" == "$CIRCLE_TAG" ]; then + make gh-pages + fi + + # For tagged builds, upload to the datatracker. + - deploy: + name: "Upload to Datatracker" + command: | + if [ "${CIRCLE_TAG#draft-}" != "$CIRCLE_TAG" ]; then + make upload + fi + + # Archive GitHub Issues + - run: + name: "Archive GitHub Issues" + command: "make archive || make archive DISABLE_ARCHIVE_FETCH=true && make gh-archive" + + # Create and store artifacts + - run: + name: "Create Artifacts" + command: "make artifacts CI_ARTIFACTS=/tmp/artifacts" + + - store_artifacts: + path: /tmp/artifacts + + - run: + name: "Prepare for Caching" + command: "git reflog expire --expire=now --all && git gc --prune=now" + + - save_cache: + name: "Saving Cache - Git" + key: v2-cache-git-{{ .Branch }}-{{ .Revision }} + paths: + - ~/draft/.git + + - save_cache: + name: "Saving Cache - Drafts" + key: v1-cache-references-{{ epoch }} + paths: + - ~/.cache/xml2rfc + + +workflows: + version: 2 + build: + jobs: + - build: + filters: + tags: + only: /.*?/ diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..66ae27a8 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Automatically generated CODEOWNERS file. +draft-ietf-jsonpath-base.md glyn.normington@gmail.comesurov.tsp@gmail.commmikulicic@gmail.comstefan.goessner@fh-dortmund.de diff --git a/.github/workflows/archive.yml b/.github/workflows/archive.yml new file mode 100644 index 00000000..fb0e0d1d --- /dev/null +++ b/.github/workflows/archive.yml @@ -0,0 +1,32 @@ +name: "Archive Issues and Pull Requests" + +on: + schedule: + - cron: '0 0 * * 0,2,4' + repository_dispatch: + types: [archive] + +jobs: + build: + name: "Archive Issues and Pull Requests" + runs-on: ubuntu-latest + steps: + - name: "Checkout" + uses: actions/checkout@v2 + + - name: "Update Archive" + uses: martinthomson/i-d-template@v1 + with: + make: archive + token: ${{ secrets.GITHUB_TOKEN }} + + - name: "Update GitHub Pages" + uses: martinthomson/i-d-template@v1 + with: + make: gh-archive + token: ${{ secrets.GITHUB_TOKEN }} + + - name: "Save Archive" + uses: actions/upload-artifact@v2 + with: + path: archive.json diff --git a/.github/workflows/ghpages.yml b/.github/workflows/ghpages.yml new file mode 100644 index 00000000..ddd6e1a0 --- /dev/null +++ b/.github/workflows/ghpages.yml @@ -0,0 +1,58 @@ +name: "Update Editor's Copy" + +on: + push: + paths-ignore: + - README.md + - CONTRIBUTING.md + - LICENSE.md + - .gitignore + pull_request: + paths-ignore: + - README.md + - CONTRIBUTING.md + - LICENSE.md + - .gitignore + +jobs: + build: + name: "Update Editor's Copy" + runs-on: ubuntu-latest + steps: + - name: "Checkout" + uses: actions/checkout@v2 + + - name: "Cache Setup" + id: cache-setup + run: | + mkdir -p "$HOME"/.cache/xml2rfc + echo "::set-output name=path::$HOME/.cache/xml2rfc" + date -u "+::set-output name=date::%FT%T" + + - name: "Cache References" + uses: actions/cache@v2 + with: + path: | + ${{ steps.cache-setup.outputs.path }} + .targets.mk + key: refcache-${{ steps.cache-setup.outputs.date }} + restore-keys: | + refcache-${{ steps.cache-setup.outputs.date }} + refcache- + + - name: "Build Drafts" + uses: martinthomson/i-d-template@v1 + + - name: "Update GitHub Pages" + uses: martinthomson/i-d-template@v1 + if: ${{ github.event_name == 'push' }} + with: + make: gh-pages + token: ${{ secrets.GITHUB_TOKEN }} + + - name: "Archive Built Drafts" + uses: actions/upload-artifact@v2 + with: + path: | + draft-*.html + draft-*.txt diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..f9dbcabb --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,49 @@ +name: "Publish New Draft Version" + +on: + push: + tags: + - "draft-*" + +jobs: + build: + name: "Publish New Draft Version" + runs-on: ubuntu-latest + steps: + - name: "Checkout" + uses: actions/checkout@v2 + + # See https://github.com/actions/checkout/issues/290 + - name: "Get Tag Annotations" + run: git fetch -f origin ${{ github.ref }}:${{ github.ref }} + + - name: "Cache Setup" + id: cache-setup + run: | + mkdir -p "$HOME"/.cache/xml2rfc + echo "::set-output name=path::$HOME/.cache/xml2rfc" + date -u "+::set-output name=date::%FT%T" + + - name: "Cache References" + uses: actions/cache@v2 + with: + path: | + ${{ steps.cache-setup.outputs.path }} + .targets.mk + key: refcache-${{ steps.date.outputs.date }} + restore-keys: | + refcache-${{ steps.date.outputs.date }} + refcache- + + - name: "Build Drafts" + uses: martinthomson/i-d-template@v1 + + - name: "Upload to Datatracker" + uses: martinthomson/i-d-template@v1 + with: + make: upload + + - name: "Archive Submitted Drafts" + uses: actions/upload-artifact@v2 + with: + path: "draft-*-[0-9][0-9].xml" diff --git a/.gitignore b/.gitignore index 4bc92383..b6657300 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,16 @@ -.refcache/ \ No newline at end of file +*.html +*.pdf +*.redxml +*.swp +*.txt +*.upload +*~ +.refcache +.tags +.targets.mk +/*-[0-9][0-9].xml +archive.json +report.xml +venv/ +lib +draft-ietf-jsonpath-base.xml diff --git a/.note.xml b/.note.xml new file mode 100644 index 00000000..26803a4a --- /dev/null +++ b/.note.xml @@ -0,0 +1,7 @@ + +Discussion of this document takes place on the + JSON Path Working Group mailing list (jsonpath@ietf.org), + which is archived at . +Source for this draft and an issue tracker can be found at + . + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0201e9ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing + +This repository relates to activities in the Internet Engineering Task Force +([IETF](https://www.ietf.org/)). All material in this repository is considered +Contributions to the IETF Standards Process, as defined in the intellectual +property policies of IETF currently designated as +[BCP 78](https://www.rfc-editor.org/info/bcp78), +[BCP 79](https://www.rfc-editor.org/info/bcp79) and the +[IETF Trust Legal Provisions (TLP) Relating to IETF Documents](http://trustee.ietf.org/trust-legal-provisions.html). + +Any edit, commit, pull request, issue, comment or other change made to this +repository constitutes Contributions to the IETF Standards Process +(https://www.ietf.org/). + +You agree to comply with all applicable IETF policies and procedures, including, +BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being +subject to a Simplified BSD License) in Contributions. + + +## Other Resources + +Discussion of this work occurs on the +[jsonpath working group mailing list](https://mailarchive.ietf.org/arch/browse/jsonpath/) +([subscribe](https://www.ietf.org/mailman/listinfo/jsonpath)). In addition to +contributions in GitHub, you are encouraged to participate in discussions there. + +**Note**: Some working groups adopt a policy whereby substantive discussion of +technical issues needs to occur on the mailing list. + +You might also like to familiarize yourself with other +[working group documents](https://datatracker.ietf.org/wg/jsonpath/documents/). diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..be523916 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,4 @@ +# License + +See the +[guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/blob/main/CONTRIBUTING.md). diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..de46d564 --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +LIBDIR := lib +include $(LIBDIR)/main.mk + +$(LIBDIR)/main.mk: +ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null)) + git submodule sync + git submodule update $(CLONE_ARGS) --init +else + git clone -q --depth 10 $(CLONE_ARGS) \ + -b main https://github.com/martinthomson/i-d-template $(LIBDIR) +endif diff --git a/README.md b/README.md index d436035e..a0d856fa 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,24 @@ -# JSONPath Internet Draft Development +# JavaScript Object Notation (JSON) Path -This repository is for the development of an Internet Draft for JSONPath. The draft is currently a work in progress. +This is the working area for the IETF [JSONPATH Working Group](https://datatracker.ietf.org/wg/jsonpath/documents/) Internet-Draft, "JavaScript Object Notation (JSON) Path". -See the latest rendered version of the draft [here](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/). +* [Editor's Copy](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/#go.draft-ietf-jsonpath-base.html) +* [Working Group Draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base) +* [Compare Editor's Copy to Working Group Draft](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/#go.draft-ietf-jsonpath-base.diff) -Christoph Burgmer's [JSONPath Comparison project](https://github.com/cburgmer/json-path-comparison) -publishes a [comparison](https://cburgmer.github.io/json-path-comparison/) of many existing -implementations of JSONPath, calculates a consensus on various features, and proposes at least one -implementation which will inform the Internet Draft. +## Building the Draft -## Community +Formatted text and HTML versions of the draft can be built using `make`. -All official discussion is on the [jsonpath@ietf.org mailing list](https://www.ietf.org/mailman/listinfo/jsonpath). -See the [archive](https://mailarchive.ietf.org/arch/browse/jsonpath/) for previous posts. - -## License - -See the draft for the copyright which is repeated in [LICENSE](./LICENSE). - -## Authoring - -The source of the Internet Draft is in markdown and corresponding `.xml`, `.txt`, and `.html` files are generated and checked in. - -So that the HTML version can be viewed via github pages, it is copied to `docs/index.html`. - -See [RFC 7991](https://tools.ietf.org/html/rfc7991) for rfc XML syntax information. - -The XML document was created from this [template](https://tools.ietf.org/tools/templates/draft-davies-template-bare-07.xml). - -In the markdown file, the convention is to start a new line when starting a new sentence. - -### Install [kramdown-rfc2629](https://github.com/cabo/kramdown-rfc2629) -``` -gem install kramdown-rfc2629 -``` -You may need to prefix the above command with `sudo` if it doesn't have sufficient permissions to complete the installation. - -### Install [xml2rfc](https://xml2rfc.tools.ietf.org/): -``` -pip3 install xml2rfc --user -``` -This will place the executable in `~/.local/bin` - -### Install [xmlstarlet](http://xmlstar.sourceforge.net/) -On macOS, issue: +```sh +$ make ``` -brew install xmlstarlet -``` -On Linux, issue something like: -``` -apt-get install -y xmlstarlet -``` - -### Install `aex` and `bap` -`aex` is an ABNF extractor and `bap` an ABNF syntax checker. +This requires that you have the necessary software installed. See +[the instructions](https://github.com/martinthomson/i-d-template/blob/master/doc/SETUP.md). -1. Clone https://github.com/fenner/bap -2. In the cloned directory execute - 1. `./configure` - 2. `make` -3. `aex` and `bap` binaries should now exist in the directory -4. Add them to your path -### Re-generate files - - This will: - - re-generate the `.txt` and `.html` files - - check the ABNF syntax - - copy the HTML file for use by github pages: - -``` -xml2rfc ./draft-ietf-jsonpath-base.xml --text --html && aex draft-ietf-jsonpath-base.txt | bap -S path -q && cp draft-ietf-jsonpath-base.html docs/index.html -``` +## Contributing -A script [gen.sh](scripts/gen.sh) is provided for convenience. You can also use [docker-gen.sh](scripts/docker-gen.sh) -version that installs and runs all utilities within a Docker container. - -### Conventions - -Basic conventions around source files formatting are captured in the `.editorconfig` file. -Many editors support that file natively. Others (such as VS code) require a plugin, see https://editorconfig.org/. - -### Pull Requests - -For ease of reading pull requests, push the PR branch to `master` of your fork. For instance, if your -github username/organisation is `xxx`, then rendered HTML will be available at: - -``` -https://xxx.github.io/draft-ietf-jsonpath-jsonpath/ -``` +See the +[guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/blob/main/CONTRIBUTING.md).