diff --git a/doc/activity.md b/doc/activity.md new file mode 100644 index 0000000..bc49240 --- /dev/null +++ b/doc/activity.md @@ -0,0 +1,20 @@ +GitBucket records several types of user activity to ```ACTIVITY``` table. Activity types are shown below: + +type | message | additional information +------------------|------------------------------------------------------|------------------------ +create_repository |$user created $owner/$repo |- +open_issue |$user opened issue $owner/$repo#$issueId |- +close_issue |$user closed issue $owner/$repo#$issueId |- +close_issue |$user closed pull request $owner/$repo#$issueId |- +reopen_issue |$user reopened issue $owner/$repo#$issueId |- +comment_issue |$user commented on issue $owner/$repo#$issueId |- +comment_issue |$user commented on pull request $owner/$repo#$issueId |- +create_wiki |$user created the $owner/$repo wiki |$page +edit_wiki |$user edited the $owner/$repo wiki |$page
$page:$commitId(since 1.5) +push |$user pushed to $owner/$repo#$branch to $owner/$repo |$commitId:$shortMessage\n* +create_tag |$user created tag $tag at $owner/$repo |- +create_branch |$user created branch $branch at $owner/$repo |- +delete_branch |$user deleted branch $branch at $owner/$repo |- +fork |$user forked $owner/$repo to $owner/$repo |- +open_pullreq |$user opened pull request $owner/$repo#issueId |- +merge_pullreq |$user merge pull request $owner/$repo#issueId |- diff --git a/doc/auto_update.md b/doc/auto_update.md new file mode 100644 index 0000000..fcce3e0 --- /dev/null +++ b/doc/auto_update.md @@ -0,0 +1,35 @@ +GitBucket uses H2 database to manage project and account data. GitBucket updates database schema automatically in the first run after the upgrading. + +To release a new version of GitBucket, add the version definition to the [servlet.AutoUpdate](https://github.com/takezoe/gitbucket/blob/master/src/main/scala/servlet/AutoUpdateListener.scala) at first. + +```scala +object AutoUpdate { + ... + /** + * The history of versions. A head of this sequence is the current BitBucket version. + */ + val versions = Seq( + Version(1, 0) + ) + ... +``` + +Next, add a SQL file which updates database schema into [/src/main/resources/update/](https://github.com/takezoe/gitbucket/tree/master/src/main/resources/update) as ```MAJOR_MINOR.sql```. + +GitBucket stores the current version to ```GITBUCKET_HOME/version``` and checks it at start-up. If the stored version differs from the actual version, it executes differences of SQL files between the stored version and the actual version. And ```GITBUCKET_HOME/version``` is updated by the actual version. + +We can also add any Scala code for upgrade GitBucket which modifies ď˝’esources other than database. Override ```Version.update``` like below: + +```scala +val versions = Seq( + new Version(1, 3){ + override def update(conn: Connection): Unit = { + super.update(conn) + // Add any code here! + } + }, + Version(1, 2), + Version(1, 1), + Version(1, 0) +) +``` diff --git a/doc/comment_action.md b/doc/comment_action.md new file mode 100644 index 0000000..5f8d9e2 --- /dev/null +++ b/doc/comment_action.md @@ -0,0 +1,46 @@ +After the issue creation at GitBucket, users can add comments or close it. +The details are saved at ```ISSUE_COMMENT``` table. + +To determine if it was any operation, you see the ```ACTION``` column. + +|ACTION| +|--------| +|comment| +|close_comment| +|reopen_comment| +|close| +|reopen| +|commit| +|merge| +|delete_branch| +|refer| + +#####comment +This value is saved when users have made a normal comment. + +#####close_comment, reopen_comment +These values are saved when users have reopened or closed the issue with comments. + +#####close, reopen +These values are saved when users have reopened or closed the issue. +At the same time, store the fixed value(i.e. "Close" or "Reopen") to the ```CONTENT``` column. +Therefore, this comment is not displayed, and not counted as a comment. + +#####commit +This value is saved when users have pushed including the ```#issueId``` to the commit message. +At the same time, store it to the ```CONTENT``` column with its commit id. +This comment is displayed. But it can not be edited by all users, and also not counted as a comment. + +#####merge +This value is saved when users have merged the pull request. +At the same time, store the message to the ```CONTENT``` column. +This comment is displayed. But it can not be edited by all users, and also not counted as a comment. + +#####delete_branch +This value is saved when users have deleted the branch. Users can delete branch after merging pull request which is requested from the same repository. +At the same time, store it to the ```CONTENT``` column with the deleted branch name. +Therefore, this comment is not displayed, and not counted as a comment. + +#####refer +This value is saved when other issue or issue comment contains reference to the issue like ```#issueId```. +At the same time, store id and title of the referrer issue as ```id:title```. diff --git a/doc/directory.md b/doc/directory.md new file mode 100644 index 0000000..77cc4d3 --- /dev/null +++ b/doc/directory.md @@ -0,0 +1,42 @@ +GitBucket persists all data into __HOME/.gitbucket__ in default (In 1.9 or before, HOME/gitbucket is default). + +This directory has following structure: + +``` +* /HOME/gitbucket + * /repositoties + * /USER_NAME + * / REPO_NAME.git (substance of repository. GitServlet sees this directory) + * / REPO_NAME + * /issues (files which are attached to issue) + * / REPO_NAME.wiki.git (wiki repository) + * /data + * /USER_NAME + * /files + * avatar.xxx (image file of user avatar) + * /plugins + * /PLUGIN_NAME + * plugin.js + * /tmp + * /_upload + * /SESSION_ID (removed at session timeout) + * current time millis + random 10 alphanumeric chars (temporary file for file uploading) + * /USER_NAME + * /init-REPO_NAME (used in repository creation and removed after it) ... unused since 1.8 + * /REPO_NAME.wiki (working directory for wiki repository) ... unused since 1.8 + * /REPO_NAME + * /download (temporary directories are created under this directory) +``` + +There are some ways to specify the data directory instead of the default location. + +1. Environment variable __GITBUCKET_HOME__ +2. System property __gitbucket.home__ (e.g. ```-Dgitbucket.home=PATH_TO_DATADIR```) +3. Command line option for embedded Jetty (e.g. ```java -jar gitbucket.war --data=PATH_TO_DATADIR```) +4. Context parameter __gitbucket.home__ in web.xml like below: +```xml + + gitbucket.home + PATH_TO_DATADIR + +``` diff --git a/doc/how_to_run.md b/doc/how_to_run.md new file mode 100644 index 0000000..9a30673 --- /dev/null +++ b/doc/how_to_run.md @@ -0,0 +1,35 @@ +for Testers +-------- + +If you want to test GitBucket, input following command at the root directory of the source tree. + +``` +C:\gitbucket> sbt ~container:start +``` + +Then access to `http://localhost:8080/` by your browser. The default administrator account is `root` and password is `root`. + +for Developers +-------- +If you want to modify source code and confirm it, you can run GitBucket in auto reloading mode as following: + +``` +C:\gitbucket> sbt +... +> container:start +... +> ~ ;copy-resources;aux-compile +``` + +Build war file +-------- + +To build war file, run the following command: + +``` +C:\gitbucket> sbt package +``` + +`gitbucket_2.11-x.x.x.war` is generated into `target/scala-2.11`. + +To build executable war file, run Ant at the top of the source tree. It generates executable `gitbucket.war` into `target/scala-2.11`. We release this war file as release artifact. Please note the current build.xml works on Windows only. Replace `sbt.bat` with `sbt.sh` in build.xml if you want to run it on Linux. diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..12d10b1 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,10 @@ +Developer's Guide +---- + * [[How to run from source tree|HowToRun]] + * [[Directory Structure|DirectoryStructure]] + * [[Mapping and Validation|Validations]] + * [[Authentication in Controller|Authentication]] + * [[About Action in Issue Comment|CommentAction]] + * [[Activity Types|Activity]] + * [[Notification Email|Notification]] + * [[Automatic Schema Updating|AutoUpdate]] diff --git a/doc/notification.md b/doc/notification.md new file mode 100644 index 0000000..314dd9d --- /dev/null +++ b/doc/notification.md @@ -0,0 +1,20 @@ +GitBucket sends email to target users by enabling the notification email by an administrator. + +The timing of the notification are as follows: + +##### at the issue registration (new issue, new pull request) +When a record is saved into the ```ISSUE``` table, GitBucket does the notification. + +##### at the comment registration +Among the records in the ```ISSUE_COMMENT``` table, them to be counted as a comment (i.e. the record ```ACTION``` column value is "comment" or "close_comment" or "reopen_comment") are saved, GitBucket does the notification. + +##### at the status update (close, reopen, merge) +When the ```CLOSED``` column value is updated, GitBucket does the notification. + +Notified users are as follows: + +* individual repository's owner +* collaborators +* participants + +However, the operation in person is excluded from the target.