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