Contributor guide

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:

• http://scala-sbt.org
• http://git-scm.com

It doesn't hurt to also have experience with JUnit 4 for writing unit tests, Scaladoc for API documentation and Markdown for other documentation:

• http://junit.org
• http://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html
• http://daringfireball.net/projects/markdown/

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

• Discuss scala-xml with other users on the Gitter chat channel
  • https://gitter.im/scala/scala-xml
• Confirm or verify issues that are submitted
  • https://github.com/scala/scala-xml/issues
• Review and verify pull requests that are submitted
  • https://github.com/scala/scala-xml/pulls
• Contribute documentation to the Wiki
  • https://github.com/scala/scala-xml/wiki
• Improve the API documentation (see Scaladoc link above)
  • http://www.scala-lang.org/api/current/scala-xml/scala/xml/index.html
• Ask and answer questions on Stack Overflow:
  • https://stackoverflow.com/questions/tagged/scala-xml
  • https://stackoverflow.com/questions/tagged/scala+xml

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 master, so create a new branch named BRANCHNAME

git checkout -b BRANCHNAME master

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.6)" 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.1.0-1e8c888", // "1.1.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/master

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

git checkout master
git fetch upstream master
git checkout BRANCHNAME
git rebase master
git push -f origin BRANCHNAME