Merge pull request #10 from freechipsproject/acknowledgments

Acknowledgments, automatically fetch contributors

.gitignore

@@ -12,3 +12,5 @@ test_run_dir
 *.anno.json
 *.v
 *.fir
+
+docs/src/main/tut/contributors.md

Makefile

@@ -60,7 +60,7 @@ apis-diagrammer: $(diagrammerTags:%=$(apis)/diagrammer/%/index.html)
 
 # Remove the output of all build targets
 clean:
-	rm -rf $(buildDir)/api docs/target
+	rm -rf $(buildDir)/api docs/target docs/src/main/tut/contributors.md
 
 # Remove everything
 mrproper:
@@ -75,9 +75,13 @@ serve: all
 	(cd docs/target/site && jekyll serve)
 
 # Build the sbt-microsite
-docs/target/site/index.html: build.sbt $(www-src) $(chisel-src) $(api-copy)
+docs/target/site/index.html: build.sbt docs/src/main/tut/contributors.md $(www-src) $(chisel-src) $(api-copy)
 	sbt ++$(scalaVersion).$(scalaMinorVersion) docs/makeMicrosite
 
+# Determine contributors
+docs/src/main/tut/contributors.md: build.sbt
+	sbt ++$(scalaVersion).$(scalaMinorVersion) contributors/determineContributors
+
 # Build API of subprojects
 chisel3/target/scala-$(scalaVersion)/unidoc/index.html: $(shell find chisel3/src chisel-testers/src -name *.scala) | chisel3/.git
 	(cd chisel3/ && sbt ++$(scalaVersion).$(scalaMinorVersion) unidoc)

build.sbt

@@ -23,6 +23,8 @@ val technologies: String =
      | - third: ["FIRRTL", "The FIRRTL circuit compiler starts after Chisel and enables backend (FPGA, ASIC, technology) specialization, automated circuit transformation, and Verilog generation."]
      |""".stripMargin
 
+val determineContributors = taskKey[Unit]("determine contributors for subprojects")
+
 lazy val micrositeSettings = Seq(
   scalaVersion := "2.12.6",
   micrositeName := "Chisel/FIRRTL",
@@ -111,9 +113,31 @@ resolvers ++= Seq(
   Resolver.sonatypeRepo("releases")
 )
 
+lazy val contributors =
+  project
+    .settings(
+      determineContributors := {
+        import java.io.{File, PrintWriter}
+        val uniqueContributors =
+          Seq( GitHubRepository("ucb-bar", "chisel2-deprecated"),
+               GitHubRepository("freechipsproject", "chisel3"),
+               GitHubRepository("freechipsproject", "firrtl"),
+               GitHubRepository("freechipsproject", "chisel-testers"),
+               GitHubRepository("freechipsproject", "treadle"),
+               GitHubRepository("freechipsproject", "diagrammer") )
+            .map(Contributors.contributors)
+            .reduce(_ ++ _)
+            .distinct
+        val writer = new PrintWriter(new File("docs/src/main/tut/contributors.md"))
+        writer.write(s"""|<!-- Automatically generated by build.sbt 'contributors' task -->
+                         |${Contributors.contributorsMarkdown(uniqueContributors)}""".stripMargin)
+        writer.close()
+      }
+    )
+
 lazy val docs = project
   .enablePlugins(MicrositesPlugin)
   .settings(commonSettings)
   .settings(micrositeSettings)
   .settings(scalacOptions ++= (Seq("-Xsource:2.11")))
-  .dependsOn(chisel)
+  .dependsOn(chisel, contributors)

docs/src/main/tut/acknowledgements.md

@@ -4,36 +4,73 @@ title:  "Acknowledgements"
 section: "Acknowledgements"
 position: 16
 ---
-Many people have helped out in the design of Chisel, and we thank them
-for their patience, bravery, and belief in a better way.  Many
-Berkeley EECS students in the Isis group gave weekly feedback as the
-design evolved including but not limited to Yunsup Lee, Andrew
-Waterman, Scott Beamer, Chris Celio, etc.  Yunsup Lee gave us feedback
-in response to the first RISC-V implementation, called TrainWreck,
-translated from Verilog to Chisel.  Andrew Waterman and Yunsup Lee
-helped us get our Verilog backend up and running and Chisel TrainWreck
-running on an FPGA.  Brian Richards was the first actual Chisel user,
-first translating (with Huy Vo) John Hauser's FPU Verilog code to
-Chisel, and later implementing generic memory blocks.  Brian gave many
-invaluable comments on the design and brought a vast experience in
-hardware design and design tools.  Chris Batten shared his fast
-multiword C++ template library that inspired our fast emulation
-library.  Huy Vo became our undergraduate research assistant and was
-the first to actually assist in the Chisel implementation.  We
-appreciate all the EECS students who participated in the Chisel
-bootcamp and proposed and worked on hardware design projects all of
-which pushed the Chisel envelope.  We appreciate the work that James
-Martin and Alex Williams did in writing and translating network and
-memory controllers and non-blocking caches.  Finally, Chisel's
-functional programming and bit-width inference ideas were inspired by
-earlier work on a hardware description language called *Gel* designed in
-collaboration with Dany Qumsiyeh and Mark Tobenkin.
-
-<!--- Who else? --->
-
-Bachrach, J., Vo, H., Richards, B., Lee, Y., Waterman, A., Avizienis, Wawrzynek, J., Asanovic, K.
- **Chisel: Constructing Hardware in a Scala Embedded Language**.
-in DAC '12.
-Bachrach, J., Qumsiyeh, D., Tobenkin, M.
- **Hardware Scripting in Gel**.
-in Field-Programmable Custom Computing Machines, 2008. FCCM '08. 16th.
+
+## Contributors
+
+Chisel, FIRRTL, and all related projects would not be possible without the contributions of our fantastic developer community.
+The following people have contributed to the current release of the projects:
+
+{% include_relative contributors.md %}
+
+## Papers
+
+While Chisel has come a long way since 2012, the original Chisel paper provides some background on motivations and an overview of the (now deprecated) Chisel 2 language:
+
+- [Bachrach, Jonathan, et al. "Chisel: constructing hardware in a scala embedded language." DAC Design Automation Conference 2012. IEEE, 2012.](https://people.eecs.berkeley.edu/~jrb/papers/chisel-dac-2012-corrected.pdf)
+
+The FIRRTL IR and FIRRTL compiler, introduced as part of Chisel 3, are discussed in both the following paper and specification[^1]:
+
+- [Izraelevitz, Adam, et al. "Reusability is FIRRTL ground: Hardware construction languages, compiler frameworks, and transformations." Proceedings of the 36th International Conference on Computer-Aided Design. IEEE Press, 2017.](https://aspire.eecs.berkeley.edu/wp/wp-content/uploads/2017/11/Reusability-is-FIRRTL-Ground-Izraelevitz.pdf)
+- [Li, Patrick S., Adam M. Izraelevitz, and Jonathan Bachrach. "Specification for the FIRRTL Language." EECS Department, University of California, Berkeley, Tech. Rep. UCB/EECS-2016-9 (2016).](https://www2.eecs.berkeley.edu/Pubs/TechRpts/2016/EECS-2016-9.pdf)
+
+Finally, Chisel's functional programming and bit-width inference ideas were inspired by earlier work on a hardware description language called *Gel*:
+
+- [Bachrach, Jonathan, Dany Qumsiyeh, and Mark Tobenkin. "Hardware scripting in gel." 2008 16th International Symposium on Field-Programmable Custom Computing Machines. IEEE, 2008.](http://people.eecs.berkeley.edu/~jrb/papers/gel-fccm-2008.pdf)
+
+## Attribution
+
+If you use Chisel in your research, consider citing:
+
+```bib
+@inproceedings{bachrach:2012:chisel,
+  author={J. {Bachrach} and H. {Vo} and B. {Richards} and Y. {Lee} and A. {Waterman} and R {Avižienis} and J. {Wawrzynek} and K. {Asanović}},
+  booktitle={DAC Design Automation Conference 2012},
+  title={Chisel: Constructing hardware in a Scala embedded language},
+  year={2012},
+  volume={},
+  number={},
+  pages={1212-1221},
+  keywords={application specific integrated circuits;C++ language;field programmable gate arrays;hardware description languages;Chisel;Scala embedded language;hardware construction language;hardware design abstraction;functional programming;type inference;high-speed C++-based cycle-accurate software simulator;low-level Verilog;FPGA;standard ASIC flow;Hardware;Hardware design languages;Generators;Registers;Wires;Vectors;Finite impulse response filter;CAD},
+  doi={10.1145/2228360.2228584},
+  ISSN={0738-100X},
+  month={June},}
+```
+
+If you use FIRRTL in your research consider citing:
+
+```bib
+@INPROCEEDINGS{8203780,
+  author={A. Izraelevitz and J. Koenig and P. Li and R. Lin and A. Wang and A. Magyar and D. Kim and C. Schmidt and C. Markley and J. Lawson and J. Bachrach},
+  booktitle={2017 IEEE/ACM International Conference on Computer-Aided Design (ICCAD)},
+  title={Reusability is FIRRTL ground: Hardware construction languages, compiler frameworks,
+  and transformations},
+  year={2017},
+  volume={},
+  number={},
+  pages={209-216},
+  keywords={field programmable gate arrays;hardware description languages;program compilers;software reusability;hardware development practices;hardware libraries;open-source hardware intermediate representation;hardware compiler transformations;Hardware construction languages;retargetable compilers;software development;virtual Cambrian explosion;hardware compiler frameworks;parameterized libraries;FIRRTL;FPGA mappings;Chisel;Flexible Intermediate Representation for RTL;Reusability;Hardware;Libraries;Hardware design languages;Field programmable gate arrays;Tools;Open source software;RTL;Design;FPGA;ASIC;Hardware;Modeling;Reusability;Hardware Design Language;Hardware Construction Language;Intermediate Representation;Compiler;Transformations;Chisel;FIRRTL},
+  doi={10.1109/ICCAD.2017.8203780},
+  ISSN={1558-2434},
+  month={Nov},}
+@techreport{Li:EECS-2016-9,
+    Author = {Li, Patrick S. and Izraelevitz, Adam M. and Bachrach, Jonathan},
+    Title = {Specification for the FIRRTL Language},
+    Institution = {EECS Department, University of California, Berkeley},
+    Year = {2016},
+    Month = {Feb},
+    URL = {http://www2.eecs.berkeley.edu/Pubs/TechRpts/2016/EECS-2016-9.html},
+    Number = {UCB/EECS-2016-9}
+}
+```
+
+[^1]: This specification is provided for historical perspective. For the latest version of the FIRRTL specification you can use [this link](https://github.com/freechipsproject/firrtl/raw/master/spec/spec.pdf).

project/Contributors.scala

@@ -0,0 +1,30 @@
+// See LICENSE for license details.
+
+import Version.GitHubRepository
+
+object Contributors {
+
+  import github4s.Github
+  import github4s.Github._
+  import github4s.free.domain.User
+  import github4s.jvm.Implicits._
+  import scalaj.http.HttpResponse
+
+  val token: Option[String] = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+
+  def contributors(repo: GitHubRepository): List[User] =
+    Github(token)
+      .repos
+      .listContributors(repo.owner, repo.repo)
+      .exec[cats.Id, HttpResponse[String]]() match {
+        case Left(e) => throw new Exception(s"Unable to fetch contributors for ${repo.serialize}. Did you misspell it?")
+        case Right(r) => r.result
+      }
+
+  def contributorsMarkdown(contributors: Seq[User]): String =
+    contributors
+      .sortWith((a: User, b: User) => a.login.toLowerCase < b.login.toLowerCase)
+      .map(a => s"- [`@${a.login}`](${a.html_url})")
+      .mkString("\n")
+
+}

project/Version.scala

@@ -1,31 +1,35 @@
 // See LICENSE for license details.
 
-sealed trait Branch { def serialize: String }
+object Version {
 
-case class SemanticVersion(major: Int, minor: Int, patch: Int) extends Branch {
-  def serialize: String = s"v$major.$minor.$patch"
-}
+  sealed trait Branch { def serialize: String }
 
-case object Master extends Branch {
-  def serialize: String = "master"
-}
+  case class SemanticVersion(major: Int, minor: Int, patch: Int) extends Branch {
+    def serialize: String = s"v$major.$minor.$patch"
+  }
 
-sealed trait Repository { def serialize: String }
+  case object Master extends Branch {
+    def serialize: String = "master"
+  }
 
-case class GitHub(organization: String, repo: String) extends Repository {
-  def serialize: String = s"https://github.com/$organization/$repo"
-}
+  sealed trait Repository {
+    def serialize: String
+    def url: String
+  }
 
-object Version {
+  case class GitHubRepository(owner: String, repo: String) extends Repository {
+    def serialize: String = s"github.com:$owner/$repo"
+    def url: String = s"https://$serialize"
+  }
 
   val versionMap: Map[String, (Repository, SemanticVersion)] = Map(
-    "chisel3"        -> (GitHub("freechipsproject", "chisel3"),        SemanticVersion(3, 1, 7)),
-    "chisel-testers" -> (GitHub("freechipsproject", "chisel-testers"), SemanticVersion(1, 2, 9)),
-    "firrtl"         -> (GitHub("freechipsproject", "firrtl"),         SemanticVersion(1, 1, 7)),
-    "treadle"        -> (GitHub("freechipsproject", "treadle"),        SemanticVersion(1, 0, 5)) )
+    "chisel3"        -> (GitHubRepository("freechipsproject", "chisel3"),        SemanticVersion(3, 1, 7)),
+    "chisel-testers" -> (GitHubRepository("freechipsproject", "chisel-testers"), SemanticVersion(1, 2, 9)),
+    "firrtl"         -> (GitHubRepository("freechipsproject", "firrtl"),         SemanticVersion(1, 1, 7)),
+    "treadle"        -> (GitHubRepository("freechipsproject", "treadle"),        SemanticVersion(1, 0, 5)) )
 
   def docSourceUrl(project: String): Seq[String] = {
-    val repo = versionMap(project)._1.serialize
+    val repo = versionMap(project)._1.url
     val branch = versionMap(project)._2.serialize
     Seq(
       "-doc-source-url",