/ CONTRIBUTING.md
CONTRIBUTING.md
1 # Contributing 2 3 Thank you for considering contributing to ArchivesSpace. It's people 4 like you that make ArchivesSpace such a wonderful application. 5 6 ## Where do I go from here? 7 8 If you have found a bug or have an idea for an enhancement or new feature, 9 check our tracking systems to see if someone else in the community has already 10 created a ticket. The majority of the open tickets are kept in our [development catalog](https://archivesspace.atlassian.net/projects/ANW/issues/ANW-418?filter=allopenissues) but there are also issues in the [ArchivesSpace GitHub repository](https://github.com/archivesspace/archivesspace/issues). 11 12 If there isn't a ticket in either of those systems, go ahead and make one. Be 13 sure to include a **title and clear description** with as much relevant 14 information as possible including **screen shots, example data, and import or 15 export files**, and, if applicable, a **code sample** or an **executable test 16 case** demonstrating the expected behavior that is not occurring. 17 18 ## Fork & create a branch 19 20 When you are ready to start working on an issue, please assign it to yourself 21 as an indication that you are working on it. Then [fork ArchivesSpace][] and 22 create a branch with a descriptive name. 23 24 A good branch name would include the ticket number in it. For example, if you 25 are working on JIRA ticket ANW-123: 26 27 ```sh 28 git checkout -b ANW-123-descriptive-short-title 29 ``` 30 31 ## Get the test suite running 32 33 ### Bootstrap 34 35 Before running any tests, you will need to set up your environment using the 36 ArchivesSpace build system. From the top level directory, type 37 38 ```sh 39 build/run bootstrap 40 ``` 41 42 ArchivesSpace has several test suites that can be run individually or all at 43 once. NOTE: running all test suites can take a while to run. The test suites that 44 are most applicable are: 45 46 - backend:test - database and API unit tests 47 - frontend:test - staff interface unit tests 48 - public:test - public user interface unit tests 49 - indexer:test - indexer unit tests 50 - headless-tests - runs all unit test suites 51 52 To run any (or all) of the test suites, use the build system. To run the backend 53 unit tests: 54 55 ```sh 56 build/run backend:test 57 ``` 58 59 ## Implement your fix, enhancement or new feature 60 61 At this point, you're ready to make your changes! Feel free to ask for help; 62 remember everyone is a beginner at first 63 64 - ArchivesSpace Core Committer's Group - ArchivesSpaceCoreCommitters@lyrasis.org 65 - ArchivesSpace Program Team - ArchivesSpaceHome@lyrasis.org 66 67 ## Look at the impact of your changes 68 69 ArchivesSpace has two separate user interfaces - staff and public - so make sure 70 to take a look at your changes in the application prior to submitting a pull 71 request. 72 73 ### Running components locally 74 75 After you have [bootstrapped the environment](#bootstrap), you can run a 76 development instance of all ArchivesSpace components. Without any configuration, 77 the devservers will spin up an Apache Derby database which will disappear once the 78 devservers have been stopped. 79 80 #### Database and API 81 82 build/run backend:devserver 83 84 #### Staff Interface 85 86 build/run frontend:devserver 87 88 #### Public User Interface 89 90 build/run public:devserver 91 92 #### Indexer for both interfaces 93 94 build/run indexer 95 96 These development servers should be run in different terminal/command window 97 sessions. To shut them down, use Control-c. 98 99 To look at changes that impact the staff interface, you will need to start up 100 the backend and frontend devservers and the indexer. 101 102 You should now be able to open <http://localhost:3000> in your browser and see 103 the staff interface. You can log in using: 104 105 _User_: admin 106 _Password_: admin 107 108 For the public user interface, you will need to start up the backend and public 109 devservers and the indexer. 110 111 You should now be able to open <http://localhost:3001> in your browser and see 112 the public user interface. 113 114 ## Make a Pull Request 115 116 At this point, you should switch back to your master branch and make sure it's 117 up to date with ArchivesSpace's master branch: 118 119 ```sh 120 git remote add upstream git@github.com:archivesspace/archivesspace.git 121 git checkout master 122 git pull upstream master 123 ``` 124 125 Then update your feature branch from your local copy of master, and push it! 126 127 ```sh 128 git checkout ANW-123-descriptive-short-title 129 git rebase master 130 git push --set-upstream origin ANW-123-descriptive-short-title 131 ``` 132 133 Finally, go to GitHub and [make a Pull Request][] :D 134 135 TravisCI will run all test suites against the pushed branch. We care about 136 quality, so your Pull Request won't be merged until all test suites pass. 137 138 ### What happens after you submit a Pull request? 139 140 All Pull Requests are reviewed by at least one member of the ArchivesSpace [Core Committer's Group](https://archivesspace.atlassian.net/wiki/spaces/ADC/pages/102893918/Core+Committers+Group). 141 142 A core committer reviews the issue/ticket associated with the Pull Request to make 143 sure they understand what the code changes are supposed to do. Next, they review 144 the code changes to see the proposed solution. Then they checkout the branch to 145 test the solution in a running instance of ArchivesSpace. 146 147 During the review, the core committer may have comments or ask questions in the 148 Pull Request. Once the comment/questions have been answered/resolved, a Pull 149 Request can only be accepted and merged into the core code base by a core 150 committer if: 151 152 - All test suites are passing. 153 - It is up-to-date with current master. 154 155 ### Keeping your Pull Request updated 156 157 If a member of the core committer's group asks you to "rebase" your Pull Request, 158 they're saying that a lot of code has changed, and that you need to update your 159 branch so it's easier to merge. 160 161 To learn more about rebasing in Git, there are a lot of [good][git rebasing] 162 [resources][interactive rebase] but here's the suggested workflow: 163 164 ```sh 165 git checkout ANW-123-descriptive-short-title 166 git pull --rebase upstream master 167 git push --force-with-lease ANW-123-descriptive-short-title 168 ``` 169 170 ## Resources 171 172 [ArchivesSpace website](https://archivesspace.org/) 173 [ArchivesSpace Wiki](https://archivesspace.atlassian.net/wiki/spaces/ADC/overview) 174 175 ### Documentation 176 177 ArchivesSpace Technical Documentation is maintained in the [tech-docs repository](https://github.com/archivesspace/tech-docs). 178 179 ### YouTube channels/videos 180 181 From development partner Hudson Molongo: 182 https://www.youtube.com/channel/UCMBmBY_CsxwJy9rJKxQrVoQ 183 184 ArchivesSpace: 185 https://www.youtube.com/channel/UCxR6D-UlSx6N6UWTeqHTjzA 186 187 [make a pull request]: https://help.github.com/articles/creating-a-pull-request 188 [git rebasing]: http://git-scm.com/book/en/Git-Branching-Rebasing 189 [interactive rebase]: https://help.github.com/articles/interactive-rebase