Contributor guide

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
• https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html
• http://daringfireball.net/projects/markdown/

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

And start the sbt build tool:

sbt

You can compile the library source code in sbt:

> compile

Run the test suite:

> test

And produce the API docs:

> doc

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:

• root
  • xmlJVM
  • xmlJS

They can be listed with the projects command in sbt:

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

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 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 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 your branch against master, then do the following:

git rebase master
git push -f origin BRANCHNAME