Skip to content

Contributor guide

Jump to bottom Edit New page
Aaron S. Hawley edited this page Apr 19, 2021 · 14 revisions

Like Scala, the scala-xml library is distributed under a modified BSD license. The copyright is held by EPFL and Lightbend.

Contributors should sign the the contributor license agreement (CLA). This is common practice in community-based free and open source software projects.

https://www.lightbend.com/contribute/cla/scala

The scala-xml project is committed to making the Scala community a welcoming and safe place for newcomers and regular contributors.

https://scala-lang.org/conduct/

This guide for contributors assumes you have some experience with Scala and the scala-xml library, but also with using sbt and git:

It doesn't hurt to also have experience with the following:

These are some of the tasks of the project you can contribute to:

  1. Discuss scala-xml with other users on the Gitter chat channel
  2. Confirm or verify issues that are submitted
  3. Review and verify pull requests that are submitted
  4. Contribute documentation to the Wiki
  5. Improve the API documentation (see Scaladoc link above)
  6. Ask and answer questions on Stack Overflow:
  7. Good first issues for new contributors are tagged as "good first issue":

To start hacking on scala-xml, first check out the source code with git:

$ git clone -o upstream git@github.com:scala/scala-xml.git

Then change to the scala-xml sub-directory:

$ cd scala-xml

You don't want to commit to main, so create a new branch named BRANCHNAME

$ git checkout -b BRANCHNAME main

Here are some good example branch names:

  • fix-escape-defect
  • improve-docs
  • upgrade-scala-2.13
  • fix-readme-typo
  • dependency-classpath-issue

After checking out a branch, you can start the sbt build tool:

$ sbt

If you want to use another version of Java, not the default, you can override it with:

$ env JAVA_HOME="$(/usr/libexec/java_home -1.8)" sbt

You can compile the library source code in sbt:

> compile

Run the test suite:

> test

And produce the API docs:

> doc

To run a single test, run testOnly:

> testOnly scala.xml.XMLTest

To pass arguments to the junit-interface, use testOnly

> testOnly -- -v scala.xml.XMLTest.*

You can access the Scala console REPL, but it doesn't use the scala-xml source code, but instead uses the version used by the Scala compiler because of a classpath issue with sbt and the Scala compiler

> console
scala> val html = """<p><a href="http://scala-lang.org/">Scala</a></p>"""
html: String = <p><a href="http://scala-lang.org/">Scala</a></p>

scala> val src = scala.xml.Source.fromString(html)
src: org.xml.sax.InputSource = org.xml.sax.InputSource@694cc703

scala> val xml = scala.xml.XML.load(src)
xml: scala.xml.Elem = <p><a href="http://scala-lang.org/">Scala</a></p>

If you want to locally publish a modified version of scala-xml to your system, first edit the build.sbt file and modify the version to be something other than SNAPSHOT. For instance, consider using the current (HEAD) git short hash:

version := "1.2.0-1e8c888", // "1.2.0-SNAPSHOT",

Which you can get from the git command:

$ git rev-parse --short HEAD
1e8c888

Since the scala-xml library has to compile to two target platforms, Java and Javascript, there are two sbt projects:

  • scala-xml
    • xml
    • xmlJS

They can be listed with the projects command in sbt:

> projects
[info] In file:~/scala-xml/
[info] 	 * scala-xml
[info] 	   xml
[info] 	   xmlJS

To change the current project, use the project in sbt:

> project xmlJS
[info] Set current project to scala-xml (in build file:~/scala-xml/)

To show the current project, use the project command with no arguments:

> project
[info] xmlJS (in build file:~/scala-xml/)

Alternatively, you can run sbt commands for a project by adding the project name before the command with a slash character

> xmlJS/compile

If you are in the root scala-xml project, you will be running a command for both projects:

> compile
[info] Compiling Scala sources to ~/scala-xml/jvm/target/scala-2.13/classes...
[info] Compiling Scala sources to ~/scala-xml/js/target/scala-2.13/classes...
[success] Total time: 84 s

If you have modified the project's sbt settings (build.sbt or project/plugins.sbt), you can re-read them by using the reload command:

> reload
[info] Loading global plugins from ~/.sbt/0.13/plugins
[info] Updating {file:~.sbt/0.13/plugins/}global-plugins...
[info] Done updating.
[info] Loading project definition from ~/scala-xml/project
[info] Updating {file:~/scala-xml/project/}scala-xml-build...
[info] Done updating.
[info] Set current project to scala-xml (in build file:~/scala-xml/)

If you want to see if dependency resolution and retrieval is working you can run the update command:

> update

If you want to remove the compiled artifacts so everything can be rebuilt:

> clean
[success] Total time: 2 s

If you decide you want to contribute a patch back, feel free to hit the fork button, see https://github.com/scala/scala-xml/fork

After forking, add your downstream origin where USERNAME is your GitHub username:

$ git remote add origin git@github.com/USERNAME/scala-xml.git

Then push your BRANCHNAME from above to your origin:

$ git push -u origin BRANCHNAME

And then create a pull request, see https://github.com/scala/scala-xml/pull/new/main

If main gets updated and you are asked to rebase your branch against main, then do the following:

$ git checkout main
$ git fetch upstream main
$ git checkout BRANCHNAME
$ git rebase main
$ git push -f origin BRANCHNAME
Add a custom footer
Add a custom sidebar
Clone this wiki locally